pykappa.system

Implements simulation of models.

class pykappa.system.RuleTally(applied=0, failed=0)

Counts outcomes of stochastic attempts to apply a rule.

Parameters:

• applied (int)

• failed (int)

applied: int = 0

failed: int = 0

property attempts: int

The total number of attempted rule applications.

class pykappa.system.System(mixture=None, rules=None, observables=None, variables=None, tokens=None, site_defaults=None, monitor=True, seed=None)

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

Parameters:

• mixture (Mixture | None)

• rules (Iterable[Rule] | None)

• observables (dict[str, Expression] | None)

• variables (dict[str, Expression] | None)

• tokens (dict[str, float] | None)

• site_defaults (dict[str, dict[str, str]] | None)

• monitor (bool)

• seed (int | None)

classmethod read_ka(filepath, seed=None)

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.

Return type:

Self

classmethod from_ka(ka_str, seed=None)

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.

Return type:

Self

classmethod from_kappa(mixture=None, rules=None, observables=None, variables=None, *args, **kwargs)

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.

Return type:

Self

set_token(name, value)

Set a token’s value.

Parameters:

• name (str)

• value (float)

Return type:

None

property mixture: Mixture

The current state of agents and their connections.

property time: float

The current simulation time.

property next_update_time: float | None

The time of the next update, or None if the system is nonreactive.

property monitor: Monitor | None

The monitor tracking simulation history, if enabled.

property rules: Mapping[str, Rule]

Maps rule names to rules.

property signatures: Mapping[str, frozenset[str]]

The complete site interface for each agent type as inferred from the rule set.

property site_defaults: Mapping[str, Mapping[str, str]]

Maps agent types to their default site states.

property observables: Mapping[str, Expression]

Maps observable names to expressions.

property variables: Mapping[str, Expression]

Maps variable names to expressions.

property tokens: Mapping[str, float]

Maps token names to their current values.

property tallies: Mapping[str, RuleTally]

Maps rule names to counts of stochastic application outcomes.

property tally_totals: RuleTally

Counts of all stochastic application attempts, combined across rules.

property tallies_table: str

A formatted summary of stochastic rule application outcomes.

property kappa_str: str

The system representation in Kappa (.ka style) format.

to_ka(filepath)

Write system information to a Kappa file.

Parameters:

filepath (str)

Return type:

None

save(filepath)

Save a checkpoint that can be continued with System.load().

Parameters:

filepath (str)

Return type:

None

classmethod load(filepath)

Load a trusted checkpoint created by System.save().

Note

Checkpoints must only be loaded from a trusted source and are intended for use with the same PyKappa and Python versions.

Parameters:

filepath (str)

Return type:

Self

add(pattern, n_copies=1)

Add instances of a pattern or component to the mixture using inferred agent signatures.

Parameters:

• pattern (Pattern | Component | str)

• n_copies (int)

Return type:

None

remove(component)

Remove a specific component from the current mixture.

Parameters:

component (Component)

Return type:

None

property reactivity: float

The total reactivity of the system.

advance_time_to(time)

Advance time without applying an update.

Raises:

ValueError – If time is outside the interval before the next update.

Parameters:

time (float)

Return type:

None

update()

Perform one simulation step.

Return type:

None

apply(transformation, n=1)

Apply a transformation immediately for a specified number of times.

Unlike update, this does not advance simulation time or use stochastic selection — the rule fires exactly n times using randomly chosen embeddings.

Parameters:

• transformation (str) – Kappa string representation of the rule.

• n (int) – Number of times to apply the rule.

Return type:

None

update_via_kasim(time)

Simulate for a given amount of time using KaSim.

Note

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

Parameters:

time (float)

Return type:

None

kd_table(volume=1.0)

Summarize kinetic constants of two-component binding/unbinding rules given volume in liters.

Parameters:

volume (float)

Return type:

str

rule_graph()

Visualize a ruleset as a site graph of local transformations.

Solid edges = bond formation; dashed edges = bond breaking. Sites that change state show their transition as site {old→new}. Creation and degradation are shown as directed edges to/from a sink node.

Note

This is a lossy projection that neglects conditions of transformations; multiple rulesets can yield the same graph.

Return type:

Source

contact_map()

Generate a graphviz contact map using the KaSa static analyzer.

Return type:

Source