torchref.kinetic.kinetics module

class torchref.kinetic.kinetics.KineticModel(flow_chart, timepoints, rate_constants=None, efficiencies=None, instrument_function='gaussian', instrument_width=10, initial_state=None, light_activated=False, activation_level=0.5, verbose=1)

Bases: DeviceMixin, Module

Configurable PyTorch module for fitting kinetic behavior.

Supports arbitrary kinetic schemes defined by relational strings: - “A->B,B->C” (sequential) - “A->B,B->A,B->C” (with back reactions) - “A->B,A->C,B->D,C->D” (parallel pathways) - “A->B,B->C,D” (D is non-reactive state)

Each transition has TWO parameters: - Reactivity constant k (rate) - Reaction efficiency η (0 to 1, controls maximum conversion)

States can have baseline occupancy offsets (default: 0, not refined).

The initial transfer is driven by photoabsorption with quasi-instant conversion around zero, with spread accounted for by an instrument function.

Parameters:

• flow_chart (str) – Relational string describing the kinetic scheme using comma-separated transitions. Standalone states (non-reactive) can be included without transitions. Example: “A->B,B->C” or “A->B,B->A,B->C,D” (D is non-reactive)

• timepoints (torch.Tensor or array-like) – Time points at which to evaluate the kinetics

• rate_constants (dict or list, optional) – Initial rate constants. Can be: - Dict mapping “A->B” to float value - List of floats (same order as transitions in flow_chart) - None (random initialization)

• efficiencies (dict or list, optional) – Initial reaction efficiencies (0-1). Same format as rate_constants. Default: all 1.0 (100% efficient)

• instrument_function (str, optional) – Type of instrument response function. Options: ‘gaussian’, ‘none’ Default: ‘gaussian’

• instrument_width (float, optional) – Width parameter for the instrument function (e.g., sigma for gaussian) Default: 0.1

• initial_state (str, optional) – Which state starts with population 1. Default: first state in flow chart

• light_activated (bool, optional) – If True, treats this as a light-activated reaction where the initial photoexcitation can only happen once. Products returning to the initial state become inactive (A*) and cannot undergo photoactivation again. Default: False

• verbose (int, optional) – Verbosity level. Default: 1

__init__(flow_chart, timepoints, rate_constants=None, efficiencies=None, instrument_function='gaussian', instrument_width=10, initial_state=None, light_activated=False, activation_level=0.5, verbose=1)

forward()

Forward pass: compute populations at all timepoints.

Returns:

populations – Population of each state at each timepoint Shape: (n_timepoints, n_states)

Return type:

torch.Tensor

set_baseline(state, occupancy, refinable=False)

Set baseline occupancy offset for a state.

Baseline occupancies are constant offsets added to the population of a state. This is useful for non-reactive background states.

Parameters:

• state (str) – Name of the state

• occupancy (float) – Baseline occupancy value (offset)

• refinable (bool, optional) – If True, this baseline becomes a refinable parameter. If False (default), it remains constant.

Examples

>>> model.set_baseline('D', 0.1, refinable=False)  # Constant 10% background
>>> model.set_baseline('E', 0.05, refinable=True)  # Refinable baseline

get_baselines()

Get current baseline occupancies for all states.

Returns:

baselines – Dictionary mapping state names to baseline occupancies

Return type:

Dict[str, float]

get_rate_constants()

Get current rate constants (k) as a dictionary.

Returns:

rate_dict – Dictionary mapping transition strings to rate constants

Return type:

Dict[str, float]

set_rate_constant(transition, value)

Set rate constant for a specific transition.

Parameters:

• transition (str) – Transition string in the format “A->B”

• value (float) – New rate constant value (must be positive)

get_efficiencies()

Get current reaction efficiencies (η) as a dictionary.

Returns:

eff_dict – Dictionary mapping transition strings to efficiencies (0-1)

Return type:

Dict[str, float]

get_effective_rates()

Get effective rates (k * η) as a dictionary.

Returns:

eff_rate_dict – Dictionary mapping transition strings to effective rates

Return type:

Dict[str, float]

get_time_constants()

Get time constants (1/k_eff) for each transition.

Returns:

time_dict – Dictionary mapping transition strings to time constants

Return type:

Dict[str, float]

parameters()

Get all flexible (learnable) parameters as a dictionary.

Returns:

params – Dictionary mapping parameter names to their tensors: - ‘log_rate_constants’: log-transformed rate constants - ‘log_instrument_width’: log-transformed instrument width (if refinable) - ‘baseline_{state}’: refinable baseline for specific states (if any)

Return type:

Dict[str, torch.Tensor]

Examples

>>> model = KineticModel(...)
>>> params = model.parameters()
>>> print(params.keys())
>>> # Use with optimizer: optimizer = torch.optim.Adam(params.values(), lr=0.01)

print_parameters()

Print current model parameters.

plot_occupancies(outpath, times=None, log=False, figsize=(10, 6), dpi=150, title=None)

Plot state occupancies over time and save to file.

Parameters:

• outpath (str) – Path to save the plot (e.g., ‘kinetics.png’)

• log (bool, optional) – If True, use log scale for x-axis. Default: False

• figsize (Tuple[int, int], optional) – Figure size (width, height). Default: (10, 6)

• dpi (int, optional) – DPI for saving figure. Default: 150

• title (str, optional) – Custom title for the plot. If None, uses flow chart string

visualize(outpath, **kwargs)

Alias for plot_occupancies for convenience.

Parameters:

• outpath (str) – Path to save the plot

• **kwargs – Additional arguments passed to plot_occupancies