pytams.sqldb

A class for the TAMS data as an SQL database using SQLAlchemy.

Attributes

valid_statuses

Classes

Base	A base class for the tables.
Trajectory	A table storing the active trajectories.
ArchivedTrajectory	A table storing the archived trajectories.
SplittingIterations	A table storing the splitting iterations.
SQLFile	An SQL file.

Module Contents

class Base

Bases: sqlalchemy.orm.DeclarativeBase

A base class for the tables.

class Trajectory

Bases: Base

A table storing the active trajectories.

id: sqlalchemy.orm.Mapped[int]

traj_file: sqlalchemy.orm.Mapped[str]

t_metadata: sqlalchemy.orm.Mapped[str]

status: sqlalchemy.orm.Mapped[str]

class ArchivedTrajectory

Bases: Base

A table storing the archived trajectories.

id: sqlalchemy.orm.Mapped[int]

t_metadata: sqlalchemy.orm.Mapped[str]

traj_file: sqlalchemy.orm.Mapped[str]

class SplittingIterations

Bases: Base

A table storing the splitting iterations.

id: sqlalchemy.orm.Mapped[int]

split_id: sqlalchemy.orm.Mapped[int]

bias: sqlalchemy.orm.Mapped[int]

weight: sqlalchemy.orm.Mapped[str]

discarded_traj_ids: sqlalchemy.orm.Mapped[str]

ancestor_traj_ids: sqlalchemy.orm.Mapped[str]

min_vals: sqlalchemy.orm.Mapped[str]

min_max: sqlalchemy.orm.Mapped[str]

status: sqlalchemy.orm.Mapped[str]

valid_statuses = ['locked', 'idle', 'completed']

class SQLFile(file_name: str, in_memory: bool = False, ro_mode: bool = False)

An SQL file.

Allows atomic access to an SQL database from all the workers.

Note: TAMS works with Python indexing starting at 0, while SQL indexing starts at 1. Trajectory ID is updated accordingly when accessing/updating the DB.

Variables:

_file_name – The file name

name() → str

Access the DB file name.

Returns:

the database name, empty string if in-memory

add_trajectory(traj_file: str, metadata: str) → None

Add a new trajectory to the DB.

Parameters:

• traj_file – The trajectory file of that trajectory

• metadata – a json representation of the traj metadata

Raises:

SQLAlchemyError if the DB could not be accessed –

update_trajectory_file(traj_id: int, traj_file: str) → None

Update a trajectory file in the DB.

Parameters:

• traj_id – The trajectory id

• traj_file – The new trajectory file of that trajectory

Raises:

SQLAlchemyError if the DB could not be accessed –

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

Set the status of a trajectory to “locked” if possible.

Parameters:

• traj_id – The trajectory id

• allow_completed_lock – Allow to lock a “completed” trajectory

Returns:

True if the trajectory was successfully locked, False otherwise

Raises:

• ValueError if the trajectory with the given id does not exist –

• SQLAlchemyError if the DB could not be accessed –

mark_trajectory_as_completed(traj_id: int) → None

Set the status of a trajectory to “completed” if possible.

Parameters:

traj_id – The trajectory id

Raises:

• ValueError if the trajectory with the given id does not exist –

• SQLAlchemyError if the DB could not be accessed –

release_trajectory(traj_id: int) → None

Set the status of a trajectory to “idle” if possible.

Parameters:

traj_id – The trajectory id

Raises:

ValueError if the trajectory with the given id does not exist –

get_trajectory_count() → int

Get the number of trajectories in the DB.

Returns:

The number of trajectories

fetch_trajectory(traj_id: int) → str

Get the trajectory file of a trajectory.

Parameters:

traj_id – The trajectory id

Returns:

The trajectory file

Raises:

ValueError if the trajectory with the given id does not exist –

release_all_trajectories() → None

Release all trajectories in the DB.

archive_trajectory(traj_file: str, metadata: str) → None

Add a new trajectory to the archive container.

Parameters:

• traj_file – The trajectory file of that trajectory

• metadata – a json representation of the traj metadata

fetch_archived_trajectory(traj_id: int) → str

Get the trajectory file of a trajectory in the archive.

Parameters:

traj_id – The trajectory id

Returns:

The trajectory file

Raises:

ValueError if the trajectory with the given id does not exist –

get_archived_trajectory_count() → int

Get the number of trajectories in the archive.

Returns:

The number of trajectories

clear_archived_trajectories() → int

Delete the content of the archived traj table.

Returns:

The number of entries deleted

add_splitting_data(k: int, bias: int, weight: float, discarded_ids: list[int], ancestor_ids: list[int], min_vals: list[float], min_max: list[float]) → None

Add a new splitting data to the DB.

Parameters:

• k – The splitting iteration index

• bias – The number of restarted trajectories

• weight – Weight of the ensemble at the current iteration

• discarded_ids – The list of discarded trajectory ids

• ancestor_ids – The list of trajectories used to restart

• min_vals – The list of minimum values

• min_max – The score minimum and maximum values

update_splitting_data(k: int, bias: int, weight: float, discarded_ids: list[int], ancestor_ids: list[int], min_vals: list[float], min_max: list[float]) → None

Update the last splitting data row to the DB.

Parameters:

• k – The splitting iteration index

• bias – The number of restarted trajectories

• weight – Weight of the ensemble at the current iteration

• discarded_ids – The list of discarded trajectory ids

• ancestor_ids – The list of trajectories used to restart

• min_vals – The list of minimum values

• min_max – The score minimum and maximum values

mark_last_iteration_as_completed() → None

Mark the last splitting iteration as complete.

By default, iteration data append to the SQL table with a state “locked” to indicate an iteration being worked on. Upon completion, mark it as “completed” otherwise the iteration is considered incomplete, i.e. interrupted by some error or wall clock limit.

get_k_split() → int

Get the current splitting iteration counter.

Returns:

The ksplit from the last entry in the SplittingIterations table

get_ongoing() → list[int] | None

Get the list of ongoing trajectories if any.

Returns:

Either a list trajectories or None if nothing was left to do

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

Read the weights from the database.

Returns:

the weight for each splitting iteration as a numpy array

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

Read the biases from the database.

Returns:

the bias for each splitting iteration as a numpy array

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

Read the min/max from the database.

Returns:

the 2D Numpy array with k_index, min, max

clear_splitting_data() → int

Delete the content of the splitting data table.

Returns:

The number of entries deleted

dump_file_json(json_file: str | None = None) → None

Dump the content of the trajectory table to a json file.

Parameters:

json_file – an optional file name (or path) to dump the data to