pytams.database

A database class for TAMS.

Classes

Database

A database class for TAMS.

Module Contents

class Database(fmodel_t: type[pytams.fmodel.ForwardModelBaseClass], params: dict[Any, Any], ntraj: int = -1, nsplititer: int = -1, read_only: bool = True)

A database class for TAMS.

The database class for TAMS 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 TAMS algorithm proceeds.

The readable files are currently in an XML format.

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

Variables:

• _fmodel_t – the forward model type

• _save_to_disk – boolean to trigger saving the database to disk

• _path – a path to an existing database to restore or a new path

• _restart – a bool to override an existing database

• _parameters – the dictionary of parameters

• _trajs_db – the list of trajectories

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

Instanciate a TAMS database from disk.

Parameters:

• a_path – the path to the database

• read_only – the database access mode

Returns:

a TAMS database object

init_active_ensemble() → None

Initialize the requested number of trajectories.

save_trajectory(traj: pytams.trajectory.Trajectory) → 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

append_traj(a_traj: pytams.trajectory.Trajectory, 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: pytams.trajectory.Trajectory, 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[pytams.trajectory.Trajectory]

Access to the trajectory list.

Returns:

Trajectory list

get_traj(idx: int) → pytams.trajectory.Trajectory

Access to a given trajectory.

Parameters:

idx – the index

Returns:

Trajectory

Raises:

ValueError if idx is out of range –

overwrite_traj(idx: int, traj: pytams.trajectory.Trajectory) → 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 –

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

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_len() → int

Length of the archived trajectory list.

Returns:

Trajectory list length

update_traj_list(a_traj_list: list[pytams.trajectory.Trajectory]) → None

Overwrite the trajectory list.

Parameters:

a_traj_list – the new trajectory list

archive_trajectory(traj: pytams.trajectory.Trajectory) → 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_ended: bool) → None

Unlock a trajectory in the SQL DB.

Parameters:

• tid – the trajectory id

• has_ended – True if the trajectory has ended

Raises:

SQLAlchemyError if the DB could not be accessed –

update_trajectory_file(traj_id: int, checkfile: pathlib.Path) → None

Update a trajectory file in the DB.

Parameters:

• traj_id – The trajectory id

• checkfile – The new checkfile of that trajectory

Raises:

SQLAlchemyError if the DB could not be accessed –

weights() → numpy.typing.NDArray[numpy.number]

Splitting iterations weights.

append_splitting_iteration_data(ksplit: int, bias: int, discarded_ids: list[int], ancestor_ids: list[int], min_vals: list[float], min_max: list[float]) → None

Append a set of splitting data to internal list.

Parameters:

• ksplit – The splitting iteration index

• bias – The number of restarted trajectories, also ref. to as bias

• discarded_ids – The list of discarded trajectory ids

• ancestor_ids – The list of trajectories used to restart (ancestors)

• min_vals – The list of minimum values

• min_max – The score minimum and maximum values

Raises:

ValueError if the provided ksplit is incompatible with the db state –

update_splitting_iteration_data(ksplit: int, bias: int, discarded_ids: list[int], ancestor_ids: list[int], min_vals: list[float], min_max: list[float]) → None

Update the last set of splitting data to internal list.

Parameters:

• ksplit – The splitting iteration index

• bias – The number of restarted trajectories, also ref. to as bias

• discarded_ids – The list of discarded trajectory ids

• ancestor_ids – The list of trajectories used to restart (ancestors)

• min_vals – The list of minimum values

• min_max – The score minimum and maximum values

Raises:

ValueError if the provided ksplit is incompatible with the db state –

mark_last_splitting_iteration_as_done() → None

Flag the last splitting iteration as done.

n_traj() → int

Return the number of trajectory used for TAMS.

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

Returns:

number of trajectory

n_split_iter() → int

Return the number of splitting iteration used for TAMS.

Note that this is the requested number of splitting iteration, not the current splitting iteration.

Returns:

number of splitting iteration

path() → str | None

Return the path to the database.

done_with_splitting() → bool

Check if we are done with splitting.

get_ongoing() → list[int] | None

Return the list of trajectories undergoing branching or None.

Ongoing trajectories are extracted from the last splitting iteration data if it has not been flaged as “completed”.

k_split() → int

Get the current splitting iteration index.

The current splitting iteration index is equal to the ksplit + bias (number of branching event in the last iteration) entries of last entry in the SQL db table

Returns:

Internal splitting iteration index

set_init_ensemble_flag(status: bool) → None

Change the initial ensemble status flag.

Parameters:

status – the new status

init_ensemble_done() → bool

Get the initial ensemble status flag.

Returns:

the flag indicating that the initial ensemble is finished

count_ended_traj() → int

Return the number of trajectories that ended.

count_converged_traj() → int

Return the number of trajectories that converged.

count_computed_steps() → int

Return the total number of steps taken.

This total count includes both the active and discarded trajectories.

get_transition_probability() → float

Return the transition probability.

info() → None

Print database info to screen.

reset_initial_ensemble_stage() → None

Reset the database content to the initial ensemble stage.

In particular, the splitting iteration data is cleared, the list of active trajectories restored and any branched trajectory data deleted.

First, the active list in the SQL db is updated, the archived list cleared and a new call to load_data update the in-memory data.

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

Plot the score as function of time for all trajectories.

plot_min_max_span(fname: str | None = None) → None

Plot the evolution of the ensemble min/max during iterations.