Skip to content

stochastic

RL4CRN.utils.stochastic

Lightweight wrappers around GPU-accelerated SSA runs.

This module provides a convenience function to run stochastic simulations (via StochasticSimulationsNew.MultiGPUsupport.SSA) over many parameter/input configurations and return a summarized pandas DataFrame suitable for quick analysis and plotting.

Key idea
  • The backend SSA typically returns raw per-trajectory samples (including metadata like GPU/thread indices).
  • quick_measurement_SSA groups the raw output by time and parameter columns, and computes mean and standard deviation trajectories for selected species, yielding a compact table (often with MultiIndex columns: (species, 'mean'), (species, 'std')).

The returned summary is designed to be compatible with downstream plotting helpers such as plot_simulation_summary.

quick_measurement_SSA(crn, parameters, parameter_names, t_fin=100, n_trajectories=100, max_threads=10000, t_step=0.1, t_control_step=-1, species_to_measure=None, max_value=1000000.0)

Run GPU-accelerated SSA for multiple parameter settings and return a compact summary.

This is a thin wrapper around SSA(...) that:

  1. distributes parameter sets across available GPUs,
  2. runs many SSA trajectories per parameter set, and
  3. aggregates the raw results into mean/std trajectories per (time, inputs).
PARAMETER DESCRIPTION
crn

Parsed CRN object consumed by the SSA backend. Expected to expose crn.species (iterable of species names).
parameters

Parameter/input configurations to simulate. Commonly used for input combinations, e.g. [(0, 0), (0, 1), (1, 0), (1, 1)].

TYPE: Sequence[tuple | list]

parameter_names

Names corresponding to each entry in a parameter tuple. These become grouping columns in the output (e.g. ['u_1', 'u_2']).

TYPE: Sequence[str]

t_fin

Final simulation time (end of time horizon).

TYPE: float DEFAULT: 100

n_trajectories

Number of independent SSA trajectories per parameter configuration.

TYPE: int DEFAULT: 100

max_threads

Maximum number of GPU threads used by the backend. (Passed through to the SSA implementation if applicable.)

TYPE: int DEFAULT: 10000

t_step

Sampling timestep for recording trajectories.

TYPE: float DEFAULT: 0.1

t_control_step

Control/update interval if the backend supports time-varying inputs. Use -1 for “no control stepping” (backend-dependent).

TYPE: float DEFAULT: -1

species_to_measure

Subset of species names to keep and summarize.

  • If None: summarize all species in crn.species that appear in the SSA dataframe.
  • If provided: silently ignores species names not present in the SSA output columns.

TYPE: list[str] | None DEFAULT: None

max_value

Divergence/overflow clamp passed to the SSA backend. If states exceed this value, the backend may flag divergence.

TYPE: float DEFAULT: 1000000.0

RETURNS DESCRIPTION

tuple[pandas.DataFrame, bool]:

  • summary_df: Aggregated dataframe with one row per unique combination of grouping columns (time + parameters), and MultiIndex measurement columns: (species, 'mean'), (species, 'std'). The grouping columns include time and all non-species, non-metadata columns (e.g., u_1, u_2, ...).
  • has_diverged: True if any trajectory/configuration was flagged as diverged in the raw SSA output (based on a has_diverged column).
Notes
  • The function assumes the raw SSA dataframe includes:
    • species columns (matching crn.species),
    • grouping columns (e.g., time and parameter/input columns),
    • optional metadata columns such as thread_index, iteration_index, gpu,
    • a boolean has_diverged column used to detect unstable simulations.
  • The aggregation is performed via: raw_df.groupby(group_cols)[target_species].agg(['mean','std']).reset_index().