pyrevs.database

Submodules

• pyrevs.database.bootstrap
• pyrevs.database.config
• pyrevs.database.database
• pyrevs.database.extension

Classes

DatabaseConfig	Database configuration.
Database	A database class for the pyREVS sampler.
DatabaseCoreSpec	A dataclass for the database core specification.
StrategyDatabaseExtension	A base extension class for specific strategies.

Functions

load_database(→ pyrevs.database.database.Database)

Load a database with its strategy extension.

Package Contents

load_database(path: pathlib.Path, read_only: bool = True) → pyrevs.database.database.Database

Load a database with its strategy extension.

class DatabaseConfig

Database configuration.

path: str | None = None

restart: bool = False

format: str = 'XML'

archive_discarded: bool = True

class Database(fmodel_t: type[pyrevs.core.ForwardModelBaseClass[T_Noise, T_State]], config: pyrevs.core.Config, read_only: bool = True)

Bases: Generic[T_Noise, T_State]

A database class for the pyREVS sampler.

The database class is a container for all the trajectory (and splitting data). When the user provides a path to store the database, a local folder is created holding a number of readable files, any output from the model and SQL files used to lock/release trajectories as the sampling algorithm proceeds.

The readable files are currently in an XML format.

A database can be loaded independently from the sampling algorithm and used for post-processing.

Variables:

• _fmodel_t – the forward model type

• _database_cfg – the database configuration dataclass

• _parameters – the dictionary of parameters

• _trajs_db – the list of trajectories

classmethod create(fmodel_t: type[pyrevs.core.ForwardModelBaseClass[T_Noise, T_State]], config: pyrevs.core.Config) → Database[T_Noise, T_State]

Create a new pyREVS database.

If no path is provided in the TOML configuration, the database is created in-memory and this is equivalent to calling the constructor.

Parameters:

• fmodel_t – the forward model type

• config – a Config object with the full configuration

Returns:

a pyREVS database object

classmethod load(a_path: pathlib.Path, read_only: bool = True) → Database[T_Noise, T_State]

Instantiate a pyREVS database from disk.

Parameters:

• a_path – the path to the database

• read_only – the database access mode

Returns:

a pyREVS database object

initialize_core_state(spec: DatabaseCoreSpec) → None

Initialize the core state of the database.

From a specification dataclass. It also updates the metadata on disk if the database is on-disk.

Parameters:

spec – the database core specification

init_traj_pool() → None

Initialize the trajectory pool.

attach_extension(ext: pyrevs.database.extension.StrategyDatabaseExtension) → None

Attach an extension to the database.

extension() → pyrevs.database.extension.StrategyDatabaseExtension

Return the extension attached to the database.

init_active_ensemble() → None

Initialize the requested number of trajectories.

save_trajectory(traj: pyrevs.trajectory.Trajectory[T_Noise, T_State]) → None

Save a trajectory to disk in the database.

Parameters:

traj – the trajectory to save

load_data(load_archived_trajectories: bool = False) → None

Load data stored into the database.

The initialization of the database only populate the metadata but not the full trajectories data.

Parameters:

load_archived_trajectories – whether to load archived trajectories

load_archived_trajectories() → None

Load the archived trajectories data.

name() → str

Accessor to DB name.

Returns:

DB name

strategy() → str

Accessor to DB strategy.

Returns:

DB strategy

to_disk() → bool

Check if the database is stored on disk.

append_traj(a_traj: pyrevs.trajectory.Trajectory[T_Noise, T_State], update_db: bool) → None

Append a Trajectory to the internal list.

Parameters:

• a_traj – the trajectory

• update_db – True to update the SQL DB content

append_archived_traj(a_traj: pyrevs.trajectory.Trajectory[T_Noise, T_State], update_db: bool) → None

Append an archived Trajectory to the internal list.

Parameters:

• a_traj – the trajectory

• update_db – True to update the SQL DB content

traj_list() → list[pyrevs.trajectory.Trajectory[T_Noise, T_State]]

Access to the trajectory list.

Returns:

Trajectory list

get_traj(idx: int) → pyrevs.trajectory.Trajectory[T_Noise, T_State]

Access to a given trajectory.

Parameters:

idx – the index

Returns:

Trajectory

Raises:

ValueError if idx is out of range –

overwrite_traj(idx: int, traj: pyrevs.trajectory.Trajectory[T_Noise, T_State]) → None

Deep copy a trajectory into internal list.

Parameters:

• idx – the index of the trajectory to override

• traj – the new trajectory

Raises:

ValueError if idx is out of range –

ping_diag_database() → None

Initialize the diagDB from the main process.

To avoid race condition in creating the DB from workers, let it be initialized from the main process here.

update_diagnostic_weights(tweight: float) → None

Update the weights of all the active trajectories.

header_file() → str

Helper returning the DB header file.

Returns:

Header file

pool_file() → str

Helper returning the DB trajectory pool file.

Returns:

Pool file

get_pool_db() → pyrevs.core.CoreDB | None

Get the pool SQL database handle.

is_empty() → bool

Check if list of trajectories is empty.

Returns:

True if the list of trajectories is empty

traj_list_len() → int

Length of the trajectory list.

Returns:

Trajectory list length

archived_traj_list() → list[pyrevs.trajectory.Trajectory[T_Noise, T_State]]

Access to the archived trajectory list.

Returns:

Archived trajectory list

archived_traj_list_len() → int

Length of the archived trajectory list.

Returns:

Trajectory list length

update_traj_list(a_traj_list: list[pyrevs.trajectory.Trajectory[T_Noise, T_State]]) → None

Overwrite the trajectory list.

Parameters:

a_traj_list – the new trajectory list

archive_trajectory(traj: pyrevs.trajectory.Trajectory[T_Noise, T_State]) → None

Archive a trajectory about to be discarded.

Parameters:

traj – the trajectory to archive

lock_trajectory(tid: int, allow_completed_lock: bool = False) → bool

Lock a trajectory in the SQL DB.

Parameters:

• tid – the trajectory id

• allow_completed_lock – True if the trajectory can be locked even if it is completed

Returns:

True if no disk DB and the trajectory was locked

Raises:

SQLAlchemyError if the DB could not be accessed –

unlock_trajectory(tid: int, has_terminated: bool) → None

Unlock a trajectory in the SQL DB.

Parameters:

• tid – the trajectory id

• has_terminated – True if the trajectory has terminated

Raises:

SQLAlchemyError if the DB could not be accessed –

update_trajectory(traj_id: int, traj: pyrevs.trajectory.Trajectory[T_Noise, T_State]) → None

Update a trajectory file in the DB.

Parameters:

• traj_id – The trajectory id

• traj – the trajectory to get the data from

Raises:

SQLAlchemyError if the DB could not be accessed –

n_traj() → int

Return the number of trajectory used for sampling run.

Note that this is the requested number of trajectory, not the current length of the trajectory pool.

Returns:

number of trajectory

path() → str | None

Return the path to the database.

count_terminated_traj() → int

Return the number of trajectories that terminated.

count_converged_traj() → int

Return the number of trajectories that converged.

all_converged() → bool

Check if all the trajectory converged.

count_computed_steps() → int

Return the total number of steps taken.

This total count includes both the active and discarded trajectories.

get_event_probability() → float

Return the event probability.

Default to a Monte-Carlo event probability if no strategy extension is attached to the database.

Returns:

the event probability

info() → None

Print database info to logger.

print_info() → None

Print database info to screen.

plot_score_functions(fname: str | None = None, plot_archived: bool = False) → None

Plot the score as function of time for all trajectories.

class DatabaseCoreSpec

A dataclass for the database core specification.

ntraj: int

strategy: str

deterministic: bool

diag_configs: dict[str, pyrevs.core.Config] | None

class StrategyDatabaseExtension

Bases: Protocol

A base extension class for specific strategies.

Currently an empty type definition might be extended in the future for pickling purposes.

abstractmethod serialize() → None

Serialize the extension.

abstractmethod deserialize() → None

Deserialize the extension.

abstractmethod get_event_probability() → float

Return the event probability.