pykappa.system¶

Classes

`Monitor`(system)	Records the history of the values of observables in a system.
`System`([mixture, rules, observables, ...])	A Kappa system containing agents, rules, observables, and variables for simulation.

class pykappa.system.Monitor(system)[source]¶

Records the history of the values of observables in a system.

Parameters:: system (System)

system¶

The system being monitored.

Type:: pykappa.system.System

history¶

Dictionary mapping observable names to their value history.

Type:: dict[str, list[float | None]]

property dataframe: DataFrame¶

Get the history of observable values as a pandas DataFrame.

Returns:: DataFrame with time and observable columns.

equilibrated(observable_name=None, tail_fraction=0.1, tolerance=0.01)[source]¶

Check if an observable (or all observables) has equilibrated based on whether the slope of recent values is sufficiently small relative to the mean.

Parameters:

observable_name (str | None) – Name of the observable to check. If None, checks all observables.
tail_fraction (float) – Fraction of the history to consider.
tolerance (float) – Maximum allowed fraction slope deviation from the mean.

Returns:

True if the observable(s) seem to have equilibrated, False otherwise.

Raises:

AssertionError – If there are not enough measurements to assess equilibration.

Return type:

bool

history: dict[str, list[float | None]]¶

measure(observable_name, time=None)[source]¶

Get the value of an observable at a specific time.

Parameters:

observable_name (str) – Name of the observable to measure.
time (float | None) – Time at which to measure. If None, uses latest time.

Returns:

Value of the observable at the specified time.

Raises:

AssertionError – If simulation hasn’t reached the specified time.

plot(combined=False)[source]¶

Make a plot of all observables over time.

Parameters:: combined (bool) – Whether to plot all observables on the same axes.
Returns:: Matplotlib figure showing trajectories of observables.
Return type:: Figure

system: System¶

tail_mean(observable_name, tail_fraction=0.1)[source]¶

Calculate the average value of an observable over a fraction of the tail.

Parameters:

observable_name (str) – Name of the observable to measure.
tail_fraction (float) – Fraction of the history to consider (from the end).

Returns:

Mean value of the observable over the tail window.

Raises:

AssertionError – If there are not enough measurements.

Return type:

float

update()[source]¶

Record current time and observable values.

Return type:: None

class pykappa.system.System(mixture=None, rules=None, observables=None, variables=None, monitor=True, seed=None)[source]¶

A Kappa system containing agents, rules, observables, and variables for simulation.

Parameters:

mixture (Mixture)
rules (dict[str, Rule])
observables (dict[str, Expression])
variables (dict[str, Expression])
monitor (Monitor | None)
seed (int | None)

mixture¶

The current state of agents and their connections.

Type:: pykappa.mixture.Mixture

rules¶

Dictionary mapping rule names to Rule objects.

Type:: dict[str, pykappa.rule.Rule]

observables¶

Dictionary mapping observable names to expressions.

Type:: dict[str, pykappa.algebra.Expression]

variables¶

Dictionary mapping variable names to expressions.

Type:: dict[str, pykappa.algebra.Expression]

monitor¶

Optional Monitor object for tracking simulation history.

Type:: pykappa.system.Monitor | None

time¶

Current simulation time.

Type:: float

tallies¶

Dictionary tracking rule application counts.

Type:: collections.defaultdict[str, dict[str, int]]

rng¶

Random number generator for reproducibility of updates.

Type:: random.Random

add_rule(rule, name=None)[source]¶

Add a new rule to the system.

Parameters:

rule (Rule | str) – Rule object or Kappa string representation.
name (str | None) – Name to assign to the rule. If None, a default name is generated.

Raises:

AssertionError – If a rule with the given name already exists.

Return type:

None

apply_rule(rule)[source]¶

Apply a rule to the mixture and update tallies.

Parameters:: rule (Rule) – Rule to apply to the current mixture.
Return type:: None

choose_rule()[source]¶

Choose a rule to apply based on reactivity weights.

Returns:: Selected rule, or None if no rules have positive reactivity.
Return type:: Rule | None

classmethod from_ka(ka_str, seed=None)[source]¶

Create a System from a Kappa (.ka style) string.

Parameters:

ka_str (str) – Kappa language string containing a system definition.
seed (int | None) – Random seed for reproducibility.

Returns:

A new System instance parsed from the string.

Return type:

Self

classmethod from_kappa(mixture=None, rules=None, observables=None, variables=None, *args, **kwargs)[source]¶

Create a System from Kappa strings.

Parameters:

mixture (dict[str, int] | None) – Dictionary mapping agent patterns to initial counts.
rules (Iterable[str] | None) – Iterable of rule strings in Kappa format.
observables (list[str] | dict[str, str] | None) – List of observable expressions or dict mapping names to expressions.
variables (dict[str, str] | None) – Dictionary mapping variable names to expressions.
*args – Additional arguments passed to System constructor.
**kwargs – Additional keyword arguments passed to System constructor.

Returns:

A new System instance.

Return type:

Self

property kappa_str: str¶: The system representation in Kappa (.ka style) format.

mixture: Mixture¶

monitor: Monitor | None¶

property names: dict[str, set[str]]¶: The names of all observables and variables.

observables: dict[str, Expression]¶

property reactivity: float¶

The total reactivity of the system.

Returns:: Sum of all rule reactivities.

classmethod read_ka(filepath, seed=None)[source]¶

Read and parse a Kappa .ka file to create a System.

Parameters:

filepath (str) – Path to the Kappa file.
seed (int | None) – Random seed for reproducibility.

Returns:

A new System instance parsed from the file.

Return type:

Self

remove_rule(name)[source]¶

Remove a rule by setting its rate to zero.

Parameters:

name (str) – Name of the rule to remove.

Raises:

AssertionError – If the rule already has zero rate.
KeyError – If no rule with the given name exists.

Return type:

None

rng: Random¶

property rule_reactivities: list[float]¶

The reactivity of each rule in the system.

Returns:: List of reactivities corresponding to system rules.

rules: dict[str, Rule]¶

set_mixture(mixture)[source]¶

Set the system’s mixture and update tracking.

Parameters:: mixture (Mixture) – New mixture to set for the system.
Return type:: None

tallies: defaultdict[str, dict[str, int]]¶

property tallies_str: str¶: A formatted string showing how many times each rule has been applied.

time: float¶

to_ka(filepath)[source]¶

Write system information to a Kappa file.

Parameters:: filepath (str) – Path where to write the Kappa file.
Return type:: None

update()[source]¶

Perform one simulation step.

Return type:: None

update_until_equilibrated(max_time=None, max_updates=None, check_interval=100, **equilibration_kwargs)[source]¶

Run simulation until all observables have equilibrated.

Parameters:

max_time (float | None) – Maximum simulation time (None for no limit).
max_updates (int | None) – Maximum number of updates (None for no limit).
check_interval (int) – Number of updates between equilibration checks.
**equilibration_kwargs – Keyword arguments passed to equilibrated (tail_fraction, tolerance).

Returns:

True if equilibrated, False if limits were reached first.

Raises:

RuntimeError – If monitoring is not enabled.

Return type:

bool

update_via_kasim(time)[source]¶

Simulate for a given amount of time using KaSim.

Note

KaSim must be installed and in the PATH. Some features may not be compatible between PyKappa and KaSim.

Parameters:: time (float) – Additional time units to simulate.
Raises:: AssertionError – If KaSim is not found in PATH.
Return type:: None

variables: dict[str, Expression]¶

wait()[source]¶

Advance simulation time according to exponential distribution.

Raises:: RuntimeWarning – If system has no reactivity (infinite wait time).
Return type:: None