pyrevs.core.fmodel

A base class for the stochastic forward model.

Attributes

T_Noise
T_State

Classes

ForwardModelBaseClass

A base class for the stochastic forward model.

Module Contents

T_Noise

T_State

class ForwardModelBaseClass(a_id: int, deterministic: bool, params: dict[str, Any] | None = None, workdir: pathlib.Path | None = None)

Bases: abc.ABC, Generic[T_Noise, T_State]

A base class for the stochastic forward model.

pyREVS relies on a separation of the stochastic model, encapsulating the physics of interest, and the sampling algorithm itself. The ForwardModelBaseClass defines the API the sampling algorithm requires from the stochastic model.

Concrete model classes must implement all the abstract functions defined in this base class.

The base class handles some components needed by pyREVS, so that the user does not have to ensure compatibility with pyREVS requirements.

Variables:

• _noise – the noise to be used in the next model step

• _step – the current stochastic step counter

• _time – the current stochastic time

• _workdir – the working directory

advance(dt: float, need_end_state: bool) → float

Base class advance function of the model.

This is the advance function called by pyREVS internals. It handles updating the model time and step counter, as well as reusing or generating noise only when needed. It also handles exceptions.

Parameters:

• dt – the time step size over which to advance

• need_end_state – whether the step end state is needed

Returns:

Some model will not do exactly dt (e.g. sub-stepping) return the actual dt

property noise: T_Noise

Return the model’s latest noise increment.

clear() → None

Destroy internal data.

set_workdir(workdir: pathlib.Path) → None

Setter of the model working directory.

Parameters:

workdir – the new working directory

abstractmethod get_current_state() → T_State

Return the current state of the model.

Note that the return type is left to the concrete model definition.

abstractmethod set_current_state(state: T_State) → None

Set the current state of the model.

Parameters:

state – the externally provide state

abstractmethod score() → float

Return the model’s current state score.

The score is a real.

Returns:

the score associated with the current model state

abstractmethod make_noise() → T_Noise

Return the model’s latest noise increment.

Note that the noise type is left to the concrete model definition.

Returns:

The model next noise increment

post_trajectory_branching_hook(step: int, time: float) → None

Model post trajectory branching hook.

Parameters:

• step – the current step counter

• time – the time of the simulation

post_trajectory_restore_hook(step: int, time: float) → None

Model post trajectory restore hook.

Parameters:

• step – the current step counter

• time – the time of the simulation

abstractmethod diagnostic_hook(dlabel: str, tid: int, score_level: float, old_snap: pyrevs.core.snapshot.Snapshot[T_Noise, T_State], new_snap: pyrevs.core.snapshot.Snapshot[T_Noise, T_State]) → Any

Diagnostic hook.

Parameters:

• dlabel – the label of the diagnostic calling the hook

• tid – the ID of the trjaectory calling

• score_level – the score level crossed and triggering the call

• old_snap – the snapshot at the beginning of the step

• new_snap – the snapshot at the end of the step

check_convergence(step: int, time: float, current_score: float, target_score: float) → bool

Check if the model has converged.

This default implementation checks if the current score is greater than or equal to the target score. The user can override this method to implement a different convergence criterion.

Parameters:

• step – the current step counter

• time – the time of the simulation

• current_score – the current score

• target_score – the target score

check_termination(step: int, time: float) → bool

Check for trajectory termination.

This default always return False. The user can override this method to implement a different termination criterion. Note that simple termination criteria (e.g. end_time, score_min) are handled elsewhere. This function should be used for more complex termination criteria, e.g. entering a given region of the model phase space.

Parameters:

• step – the current step counter

• time – the time of the simulation

classmethod name() → str

Return a the model name.