pytams.diagdb
=============

.. py:module:: pytams.diagdb

.. autoapi-nested-parse::

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



Classes
-------

.. autoapisummary::

   pytams.diagdb.DiagBase
   pytams.diagdb.DiagnosticEntry
   pytams.diagdb.DiagDB


Module Contents
---------------

.. py:class:: DiagBase

   Bases: :py:obj:`sqlalchemy.orm.DeclarativeBase`


   A base class for the tables.


.. py:class:: DiagnosticEntry

   Bases: :py:obj:`DiagBase`


   Table for recording model data at specific score levels.


   .. py:attribute:: id
      :type:  sqlalchemy.orm.Mapped[int]


   .. py:attribute:: traj_id
      :type:  sqlalchemy.orm.Mapped[int]


   .. py:attribute:: level_crossed
      :type:  sqlalchemy.orm.Mapped[float]


   .. py:attribute:: time
      :type:  sqlalchemy.orm.Mapped[float]


   .. py:attribute:: weight
      :type:  sqlalchemy.orm.Mapped[float]


   .. py:attribute:: model_data
      :type:  sqlalchemy.orm.Mapped[bytes]


   .. py:attribute:: active
      :type:  sqlalchemy.orm.Mapped[bool]


   .. py:attribute:: diaglabel
      :type:  sqlalchemy.orm.Mapped[str]


.. py:class:: DiagDB(file_name: str, in_memory: bool = False, ro_mode: bool = False)

   Bases: :py:obj:`pytams.sqlmanager.BaseSQLManager`


   A database to keep track of the diagnostics data.

   Diagnostic entries are agregated in single table. Each entry
   is associated to a trajectory and its weight in the ensemble.


   .. py:method:: add_diagnostic_entry(diaglabel: str, traj_id: int, level: float, time: float, weight: float, ldata: bytes) -> None

      Atomic insert of a diagnostic snapshot.

      The data schema assumes that any new addition to the database is
      made on an active trajectory.

      :param diaglabel: the label of the diagnostic inserting the entry
      :param traj_id: the ID of the traj adding the entry
      :param level: the score level of the entry
      :param time: the trajectory time at which the diagnostic was triggered
      :param weight: the weight of the trajectory
      :param ldata: the actual model data stored in the database



   .. py:method:: get_highest_recorded_level(traj_id: int, label: str) -> float

      Return the maximum level already recorded for this traj/label.

      :param traj_id: the ID of a trajectory
      :param label: the label of the diagnostic targeter

      :returns: the highest value of level_crossed



   .. py:method:: duplicate_diagnostic_history(ancestor_id: int, discarded_id: int, new_id: int, new_weight: float, threshold: float) -> int

      Copy diagnostic entries from an ancestor to a descendant.

      Copies all entries where level_crossed <= threshold.
      Returns the number of entries duplicated.

      The entries belonging to the discarded trajectory are set
      to inactive.

      :param ancestor_id: the ID of the ancestor to copy data from
      :param discarded_id: the ID of the discarded trajectory (during TAMS iterations)
      :param new_id: the ID of the new child trajectory
      :param new_weight: the weight of the new child trajectory
      :param threshold: the score threshold up to which copy must be performed



   .. py:method:: update_all_active_weights(new_weight: float) -> int

      Update all the active trajectories weight.

      :param new_weight: the updated weight

      :returns: the number of trajectory updated



   .. py:method:: get_diagnostic_data(label: str) -> dict[float, list[tuple[Any, float]]]

      Retrieve all diagnostic snapshots for a specific label.

      :param label: the label of the diagnostic of interest

      :returns: A dictionary mapping each iso-level (float) to a list of tuples.
                Each tuple contains (unpickled_data, trajectory_weight).



   .. py:method:: dump_to_json(json_path: str) -> None

      Export the entire diagnostic database to a JSON file.

      Note that the content of the data stored in the database is
      omitted. Only the metadata of each stored data is dumpe for debuggin purposes.



   .. py:method:: close() -> None

      Dispose of the engine and clear connections.