kappybara.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 kappybara.system.Monitor(system)

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

Parameters:

system (System)

system

The system being monitored.

Type:

kappybara.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.

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

measure(observable_name, time=None)

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)

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

update()

Record current time and observable values.

Return type:

None

class kappybara.system.System(mixture=None, rules=None, observables=None, variables=None, monitor=True)

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)

mixture

The current state of agents and their connections.

Type:

kappybara.mixture.Mixture

rules

Dictionary mapping rule names to Rule objects.

Type:

dict[str, kappybara.rule.Rule]

observables

Dictionary mapping observable names to expressions.

Type:

dict[str, kappybara.algebra.Expression]

variables

Dictionary mapping variable names to expressions.

Type:

dict[str, kappybara.algebra.Expression]

monitor

Optional Monitor object for tracking simulation history.

Type:

kappybara.system.Monitor | None

time

Current simulation time.

Type:

float

tallies

Dictionary tracking rule application counts.

Type:

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

add_rule(rule, name=None)

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)

Apply a rule to the mixture and update tallies.

Parameters:

rule (Rule) – Rule to apply to the current mixture.

Return type:

None

choose_rule()

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)

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

Parameters:

ka_str (str) – Kappa language string containing a system definition.

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)

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)

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

Parameters:

filepath (str) – Path to the Kappa file.

Returns:

A new System instance parsed from the file.

Return type:

Self

remove_rule(name)

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

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)

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.

Returns:

Tab-separated string showing applied and failed counts for each rule.

time: float

to_ka(filepath)

Write system information to a Kappa file.

Parameters:

filepath (str) – Path where to write the Kappa file.

Return type:

None

update()

Perform one simulation step.

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 may not be compatible between Kappybara 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()

Advance simulation time according to exponential distribution.

Raises:

RuntimeWarning – If system has no reactivity (infinite wait time).

Return type:

None