pyrevs.core.sqlcore

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

Attributes

valid_statuses

Classes

CoreBase	A base class for the tables.
Trajectory	A table storing the active trajectories.
ArchivedTrajectory	A table storing the archived trajectories.
CoreDB	A database holding pyREVS trajectories.

Module Contents

class CoreBase

Bases: sqlalchemy.orm.DeclarativeBase

A base class for the tables.

class Trajectory

Bases: CoreBase

A table storing the active trajectories.

id: sqlalchemy.orm.Mapped[int]

traj_file: sqlalchemy.orm.Mapped[str]

t_metadata: sqlalchemy.orm.Mapped[dict]

status: sqlalchemy.orm.Mapped[str]

class ArchivedTrajectory

Bases: CoreBase

A table storing the archived trajectories.

id: sqlalchemy.orm.Mapped[int]

traj_file: sqlalchemy.orm.Mapped[str]

t_metadata: sqlalchemy.orm.Mapped[dict]

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

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

Bases: pyrevs.core.sqlmanager.BaseSQLManager

A database holding pyREVS trajectories.

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

Note: pyREVS 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

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

Add a new trajectory to the DB.

Parameters:

• traj_file – The trajectory file of that trajectory

• metadata – a dict with the metadata

Raises:

SQLAlchemyError if the DB could not be accessed –

update_trajectory(traj_id: int, traj_file: str, metadata: dict) → None

Update a given trajectory data in the DB.

Parameters:

• traj_id – The trajectory id

• traj_file – The new trajectory file of that trajectory

• metadata – a dict with the trajectory metadata

Raises:

SQLAlchemyError if the DB could not be accessed –

update_trajectory_weight(traj_id: int, weight: float) → None

Update a given trajectory weight in the DB.

Parameters:

• traj_id – The trajectory id

• weight – the new trajectory weight

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

get_terminated_trajectory_count() → int

Return the number of trajectories that have ‘terminated’ in their metadata.

get_converged_trajectory_count() → int

Return the number of trajectories that have ‘converged’ in their metadata.

get_total_computed_steps() → int

Sum the ‘nstep_compute’ field across all active and archived trajectories.

fetch_trajectory(traj_id: int) → tuple[str, dict]

Get the trajectory file of a trajectory.

Parameters:

traj_id – The trajectory id

Returns:

A tuple with trajectory file as a str and the trajectory metadata as dict

Raises:

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

check_trajectory_exist(traj_id: int) → bool

Check if a trajectory exist for a given index.

Parameters:

traj_id – The trajectory id

Returns:

True if the trajectory exist, False otherwise

release_all_trajectories() → None

Release all trajectories in the DB.

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

Add a new trajectory to the archive container.

Parameters:

• traj_file – The trajectory file of that trajectory

• metadata – a dict with the traj metadata

fetch_archived_trajectory(traj_id: int) → tuple[str, dict]

Get the trajectory file of a trajectory in the archive.

Parameters:

traj_id – The trajectory id

Returns:

A tuple with trajectory file as a str and the trajectory metadata as dict

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

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