pykappa.system

Classes

System([mixture, rules, observables, ...])

A Kappa system containing agents, rules, observables, and variables for simulation.
class pykappa.system.System(mixture=None, rules=None, observables=None, variables=None, tokens=None, site_defaults=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])

  • tokens (dict[str, float])

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

  • monitor (Monitor | None)

  • seed (int | None)

mixture: Mixture

The current state of agents and their connections

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.

Return type:

Self

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.

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.

Return type:

Self

rules: dict[str, Rule]

Maps rule names to Rule objects

observables: dict[str, Expression]

Maps observable names to expressions

variables: dict[str, Expression]

Maps variable names to expressions

site_defaults: dict[str, dict[str, str]]

Maps agent types to site default states

time: float

Current simulation time

tokens: dict[str, float]

Maps token names to their current values

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

Tracks rule applications

monitor: Monitor | None

Optionally tracks simulation history

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

The complete site interface for each agent type inferrred from all rules.

property tallies_str: str

A formatted string showing how many times each rule has been applied.

property kappa_str: str

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

to_ka(filepath)[source]

Write system information to a Kappa file.

Parameters:

filepath (str)

Return type:

None

add(pattern, n_copies=1)[source]

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

Parameters:
Return type:

None

property reactivity: float

The total reactivity of the system.

update()[source]

Perform one simulation step.

Return type:

None

apply(transformation, n=1)[source]

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)[source]

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)[source]

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

Parameters:

volume (float)

Return type:

str

rule_graph()[source]

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()[source]

Generate a graphviz contact map using the KaSa static analyzer.

Return type:

Source