The Kappy API

Kappa graph handler

class kappy.kappa_graph.KappaAgent(typ: str, node_id, sites: dict)

class for representing one kappa agent inside a complex

abc.Sized: len returns its number of sites.

abc.Iterable: iter returns an iterator over the tuple (site_name : str, s : KappaSite)

Use self[site_name] to get a site.


Destination of the edges.

Parameters:complx (KappaComplex) – Complex self is part of
Returns:list of KappaAgent


potential duplicates and self listing.


::returns: the id of the agent if present (else Null)

get_type() → str

::returns: the type of the agent

class kappy.kappa_graph.KappaComplex(agents)

Class for representing a Kappa connected component

The string representation is the corresponding Kappa code.

abc.Sized: len returns the number of agents in the complex (the size).

abc.Iterable: iter returns an iterator on the agents it contains. Use method items() to get an iterator over the tuples (coordinates,agent).

abc.Container: x in y returns whether the pattern x occurs in y (in term of “Kappa embedding”). Use y.find_pattern(x) to get the embeddings.

Use self[coordinates] to get the agent at coordinates.

Returns:a dictionary from type : str to coordinates of agents of type type
agent_ids_of_type(type: str)
Returns:the list of coordinates of agents of type type
Returns:a list of dictionnary coordinates -> coordinates. Each dictionnary represents an embedding of ref in the complex.
classmethod from_JSONDecoder(data)

Build a KappaComplex from its JSON representation

classmethod from_string(expression)

Build a KappaComplex from its Kappa syntax

Returns:an Iterator where the items are turples (coordinates,agent)
class kappy.kappa_graph.KappaSite(*, links=None, internals=None, future_link=None, future_internal=None)

class for representing one site of a kappa agent (in a complex)

get_internal_state() → str
Returns:if any, the internal state of the site when there can only be 1 by invarient (because it is a pattern/rule/snapshot/…). None if there is not.
Returns:whether the link state is neither free nor unspecified?
Returns:the list of KappaAgent connected to here in complx
class kappy.kappa_graph.KappaSnapshot(*, time: float, event: int, complexes: list = [], tokens: dict = {})

class for representing a kappa snapshot

The string representation is the corresponding Kappa code.


Get the list of complexes.

Returns:a list of pairs (abundance: int, complex : KappaComplex)

Get after how many simulation event the snapshot was taken


Get complexes by abundance. Abundance here means copy number.

Returns:dict abundance -> list_of_complexes_that_abundant

Get complexes by size. Size here means the number of agents.

Returns:dict size -> list_of_pair_abundance_complexes_of_that_size
Returns:list of the largest KappaComplexes with their abundance.
Returns:list of the least abundant KappaComplexes.
Returns:list of the most abundant KappaComplexes.
Returns:dict size : int -> number_of_complexes_of_that_size
Returns:list of the smallest KappaComplexes with their adundance.
get_token_abundance(token: str) → int

Get the abundance of token

get_total_mass() → int

Get the total number of agents


Get the simulation time at which the snapshot was taken


Get the dictionnary token : str -> abundance : int

exception kappy.kappa_graph.KappaSyntaxError

Utilities for interaction with tools

Shared functions of api client for the kappa programming language

class kappy.kappa_common.SimulationParameter(plot_period: float, pause_condition: str, seed: int = None, store_trace: bool = False)

Parameters needed to run a simulation

  • plot_period – How often values of observables should be computed during the simulation
  • pause_condition – (a boolean kappa expression) When the simulation will stop itself and wait for further actions.
  • seed – specify the seed of the random number generator used by the simulator
  • store_trace – Because simulation traces become huge, you must specify before starting a simulation whether you may query it later
class kappy.kappa_common.PlotLimit(offset=None, points=None)

Parameters of plot query

  • points – maximum number of column that the reply should contains. (None means unlimited)
  • offset – At what column number the reply should start (None means return the end of the simulation)
exception kappy.kappa_common.KappaError(errors)

Error returned from the Kappa server

Kappa tool driver

Client for the kappa programming language through standard channel api

class kappy.kappa_std.KappaStd(kappa_bin_path=None, delimiter='x1e', args=None)

Kappa tools driver run locally.

kappa_bin_path – where to find kappa executables
(None means use the binaries bundled in the package)
delimiter – What to use to delimit messages (must not appears in
message body default ‘x1e’)

args – arguments to pass to kappa executables

add_model_file(model_fpath, position=1, file_id=None)

Add a kappa model from a file at given path to the project.

add_model_string(model_str, position=1, file_id=None)

Add a kappa model given in a string to the project.


Returns a bunch of invarients on the last parsed model


Returns the contact of the last parsed model

Parameters:accuracy (str) – “high” means take into account reachability from initial state. “low” means don’t.

Returns the dead rules of the last parsed model


Returns the influence_map of the last parsed model

Parameters:accuracy (str) – level can be “low”, “medium”, “high” or “full”. Default is medium.
analyses_potential_polymers(accuracy_cm='high', accuracy_scc='high')

Returns the list of potential polymers of the last parsed model


Add a file to the project

Parameters:file_object – a Kappa_common.File

Remove a file from the project


Returns file file_id stored in the project


Lists the files of the project (returns a FileMetadata array)


Get the default SimulationParameter instance.


Check if the current simulation is running.

project_overwrite(ast, file_id='model.ka')

Overwrite the project with the given AST

  • ast – the ast in the format returned by project_parse
  • file_id (str) – a virtual file name in which the ast will be dump
project_parse(sharing_level='compatible_patterns', **kwargs)

Parses the project

Parameters:kwargs – list of algebraic variables to overwrite Each element has the form variable_name=numerical_val
set_default_sim_param(*args, **kwargs)

Set the simulation default simulation parameters.

You can pass one of two things in as input: - a kappa_common.SimulationParameter instance - the arguments and keyword argument to create such an instance.

The parameters you specify will be used by default in simulations run by this client.


Shut down kappa instance.

Given a key to a kappa service shutdown a running kappa instance.


Returns a given generated DIN


Lists DIN generated during the simulation


Restarts a paused simulation


Deletes running/paused simulation


Returns the file file_line_id generated by $PRINT interventions


Returns state and progress of the simulation


Lists files generated by $PRINT during the simulation


Fires a intervention in a paused simulation


Returns simulation log


Pauses a simulation


Returns the plot data of the simulation

Note: No actual plot is produced as a result of this function call.

  • limit – optionnal boundaries to only get a subplot
  • format – { offset : 100, nb_points : 500 } returns the last points if offset is Null

simulation_results – a json containing the data from the simulation.


Returns a given generated snapshot


Lists snapshots generated during the simulation


Start the simulation from the last parsed model.

Parameters:simulation_parameter – a kappa_common.SimulationParameter instance. The default is set using the set_default_sim_param method.

Block until the simulation is done or timeout seconds exceeded.

If the simulation stops before timeout, siminfo is returned.