pytams.trajectory ================= .. py:module:: pytams.trajectory Exceptions ---------- .. autoapisummary:: pytams.trajectory.WallTimeLimitError Classes ------- .. autoapisummary:: pytams.trajectory.Snapshot pytams.trajectory.Trajectory Functions --------- .. autoapisummary:: pytams.trajectory.form_trajectory_id pytams.trajectory.get_index_from_id Module Contents --------------- .. py:exception:: WallTimeLimitError Bases: :py:obj:`Exception` Exception for running into wall time limit. .. py:function:: form_trajectory_id(n: int, nb: int = 0) -> str Helper to assemble a trajectory ID string. :param n: trajectory index :param nb: number of branching :returns: trajectory ID .. py:function:: get_index_from_id(identity: str) -> tuple[int, int] Helper to get trajectory index from ID string. :param identity: trajectory ID :returns: trajectory index and number of branching .. py:class:: Snapshot A dataclass defining a snapshot. Gathering what defines a snapshot into an object. The time and score are of float type, but the actual type of the noise and state are completely determined by the forward model. A snapshot is allowed to have a state or not to accomodate memory savings. :ivar time: snapshot time :ivar score: score function value :ivar noise: noise used to reach this snapshot :ivar state: model state .. py:attribute:: time :type: float .. py:attribute:: score :type: float .. py:attribute:: noise :type: Any .. py:attribute:: state :type: Any | None :value: None .. py:method:: has_state() -> bool Check if snapshot has state. :returns: True if state is not None :rtype: bool .. py:class:: Trajectory(traj_id: int, fmodel_t: type[pytams.fmodel.ForwardModelBaseClass] | None, parameters: dict[Any, Any], workdir: pathlib.Path | None = None, frozen: bool = False) A class defining a stochastic trajectory. The trajectory class is a container for time-ordered snapshots. It contains an instance of the forward model, current and end times, and a list of the model snapshots. Note that the class uses a plain list of snapshots and not a more computationally efficient data structure such as a numpy array for convenience. It is assumed that the computational cost of running TAMS reside in the forward model and the overhead of the trajectory class is negligible. It also provide the forward model with the necessary context to advance in time, method to move forward in time, methods to save/load the trajectory to/from disk as well as accessor to the trajectory history (time, state, score, ...). :ivar _parameters_full: the full parameters dictionary :ivar _tid: the trajectory index :ivar _checkFile: the trajectory checkpoint file :ivar _workdir: the model working directory :ivar _score_max: the maximum score :ivar _snaps: a list of snapshots :ivar _step: the current step counter :ivar _t_cur: the current time :ivar _t_end: the end time :ivar _dt: the stochastic time step size .. py:method:: set_checkfile(path: pathlib.Path) -> None Setter of the trajectory checkFile. :param path: the new checkFile .. py:method:: set_workdir(path: pathlib.Path) -> None Setter of the trajectory working directory. And propagate the workdir to the forward model. :param path: the new working directory .. py:method:: get_workdir() -> pathlib.Path Get the trajectory working directory. :returns: the working directory .. py:method:: id() -> int Return trajectory Id. :returns: the trajectory id .. py:method:: idstr() -> str Return trajectory Id as a padded string. :returns: the trajectory id as a string .. py:method:: advance(t_end: float = 1000000000000.0, walltime: float = 1000000000000.0) -> None Advance the trajectory to a prescribed end time. This is the main time loop of the trajectory object. Unless specified otherwise, the trajectory will advance until the end time is reached or the model has converged. If the walltime limit is reached, a WallTimeLimitError exception is raised. Note that this exception is treated as a warning not an error by the TAMS workers. :param t_end: the end time of the advance :param walltime: a walltime limit to advance the model to t_end :returns: None :raises WallTimeLimitError: if the walltime limit is reached .. py:method:: restore_from_checkfile(checkfile: pathlib.Path, fmodel_t: type[pytams.fmodel.ForwardModelBaseClass], parameters: dict[Any, Any], workdir: pathlib.Path | None = None, frozen: bool = False) -> Trajectory :classmethod: Return a trajectory restored from an XML chkfile. .. py:method:: branch_from_trajectory(from_traj: Trajectory, rst_traj: Trajectory, score: float) -> Trajectory :classmethod: Create a new trajectory. Loading the beginning of a provided trajectory for all entries with score below a given score. This effectively branches the trajectory. Although the rst_traj is provided as an argument, it is only used to set metadata of the branched trajectory. :param from_traj: an already existing trajectory to restart from :param rst_traj: the trajectory being restarted :param score: a threshold score .. py:method:: store(traj_file: pathlib.Path | None = None) -> None Store the trajectory to an XML chkfile. .. py:method:: update_metadata() -> None Update trajectory score/ending metadata. Update the maximum of the score function over the trajectory as well as the bool values for has_converged and has_ended. .. py:method:: current_time() -> float Return the current trajectory time. .. py:method:: step_size() -> float Return the time step size. .. py:method:: score_max() -> float Return the maximum of the score function. .. py:method:: is_converged() -> bool Return True for converged trajectory. .. py:method:: has_ended() -> bool Return True for terminated trajectory. .. py:method:: has_started() -> bool Return True if computation has started. .. py:method:: get_checkfile() -> pathlib.Path Return the trajectory check file name. .. py:method:: get_time_array() -> numpy.typing.NDArray[numpy.number] Return the trajectory time instants. .. py:method:: get_score_array() -> numpy.typing.NDArray[numpy.number] Return the trajectory scores. .. py:method:: get_noise_array() -> numpy.typing.NDArray[Any] Return the trajectory noises. .. py:method:: get_length() -> int Return the trajectory length. .. py:method:: get_nbranching() -> int Return the number of branching events. .. py:method:: get_last_state() -> Any | None Return the last state in the trajectory.