viridicle API¶

class viridicle.Geography(sites, rules: Union[numpy.ndarray, Sequence[str]], generator: Optional[Union[int, numpy.random._generator.Generator]] = None, num_states: Optional[int] = None)¶

This is a base class for all viridicle simulations. It must be used in a subclass.

In all Geography s, the local behavior of the system is specified using one property, the 4-dimensional numpy.ndarray beta. beta specifies the rate at which transitions occur: in every time step, we randomly select a pair of neighboring sites. If (cur_state_1, cur_state_2) is the current states of those sites, then the probability that they transition in that time step to (new_state_1, new_state_2) is given by beta[cur_state_1, cur_state_2, new_state_1, new_state_2].

Besides beta, the current state of the system is specified by a property sites. In most Geography s, sites will be a numpy.ndarray, but it may have other types.

All subclasses of Geography must provide the following methods:

_coerce_to_sites: Should coerce the input provided as sites into a sites object of the appropriate type. encode: This function should return a dictionary of graph-specific parameters that must be passed to _C.run_system: the sites numpy.ndarray, the graph_type integer, and optionally a neighborhoods, edges, and edge_idxs numpy.ndarrays. Further requirements are discussed in the docstring for the encode method. decode: This function should accept a dictionary in the same form returned by encode and convert it back to the sites property, of whatever class is used by this Geography. Further requirements are discussed in the docstring for the decode method.

Subclasses must also provide the following properties:

num_directed_edges: Number of directed edges in the graph. This is used: in calculating rate scaling.

Subclasses should provide the following properties:

num_sites: Number of vertices in the graph.

Parameters

sites – The current state of the system.
rules (Listr[str] or numpy.ndarray) – Rules for the system transition. This can be provided either as a 4-dimensional numpy.ndarray where entry rules[i, j, k, l] gives the probability of the transition (i,j)->(k,l) in a single time step, or it can be provided as a list of strings given transition rules. See the add_rule method for how these strings are interpreted and converted into an array.
generator (optional, int or numpy.random.Generator) – Random number generator. If an integer is provided, a new generator is constructed using that number as the seed for a default numpy random number generator.
num_states (optional, int) – Number of possible states in the system. This is only needed if you are specifying your rules as a list of strings.

add_rule(rule: str)¶

Adds a transition rule. Rules are expected to be strings of the form:

"i,j->k,l@r"

Where i, j, k, and l are integers giving a state, and r is a float giving the transition probability in a time step. A wildcard “*” is also allowed, but only one wildcard is allowed on either side of the ->, and is assumed to represent the same value on both sides - so, for example, if our system has two states, and we are provided the rule:

"*1->*[email protected]"

This is interpreted as the pair of rules:

"01->[email protected]",
"11->[email protected]"

Parameters: rule (str) – Rule to be added.

decode(sites: numpy.ndarray)¶

Converts a numpy.ndarray of site data to the form to be stored as the sites property. For most Geography s, this is a no-op, but for Geography s that store sites as a different class (e.g. ArbitraryGeography, where it is a networkx.Graph), this may require some additional work.

In addition, decode must be able to accept an array that has an additional dimension at the end relative to the internal sites array, for use in decoding a returned sites record. For example, suppose we have an ArbitraryGeography which we run with return_sites=True. sites is a networkx.Graph, which the encode method converts to a 1-dimensional numpy.ndarray, of shape (N,). The sites record is then returned as a 2-dimensional array of shape (N, T). We want to then decode the array into a new networkx.Graph where each vertex has associated to it a 1- dimensional array of shape (T,).

Parameters: sites (numpy.ndarray) – Array to be decoded.
Returns: Sites decoded to the proper format for this graph type.

encode() → Dict¶

Returns a dictionary of parameters to be passed to the C layer.

The dictionary must include the following keys:

‘graph_type’ (int): This must be a numerical value instructing the C layer in how to interpret the contents of the parameters. The options are:

0: The graph is fully-connected. 1: The graph is a lattice. An additional key, ‘neighbors’, must also be provided, containing a numpy.ndarray; see the LatticeGeography for details. 2: The graph has arbitrary structure. Two additional keys, ‘edges’ and ‘edge_idxs’, must also be provided, containing numpy.ndarray`s; see the :class:`ArbitraryGeography for details.

‘sites’ (numpy.ndarray): This must encode the states of the different vertices. Note that this must be a numpy.ndarray, even though the C layer can technically accept other classes that will be coerced, because the _C.run_system function will modify it in place, and this is how the new sites array is returned to update the sites parameter.

Returns: Dictionary of parameters.

property is_directed: bool¶: Whether the graph is directed.

property num_directed_edges: int¶: Number of directed edges in the system.

property num_states: int¶: Number of possible system states.

run(elapsed_time: Optional[float] = None, num_steps: Optional[int] = None, report_every: Optional[float] = None, return_counts: bool = True, return_sites: bool = False, allow_diffusion_trick: bool = True)¶

Runs the system for a specified amount of time using the Gillespie algorithm. Depending on the choice of parameters, may return a numpy.ndarray containing the counts of each site state at every reporting interval, and/or a numpy.ndarray containing the entire system at each reporting interval.

The user may specify either the amount of time to run the system, or the number of steps, but may not specify both.

Parameters

elapsed_time (optional, float) – Amount of time to run the system.
num_steps (optional, int) – Number of steps to run the system. May be specified in place of elapsed_time.
report_every (optional, float) – How often to record telemetry. If not set, return only the initial and final states. Is interpreted as either time or number of steps, depending on which of elapsed_time or num_steps is set.
return_counts (bool) – Whether to return population counts at every reporting interval. Default True.
return_sites (bool) – Whether to return the full sites array at every reporting interval. Default False.
allow_diffusion_trick (bool) – Whether to allow the use of the diffusion trick. This reduces runtime, but can cause very slight inaccuracy in the model if the diffusion rate is extremely high.

Returns

Depending on parameters set, can return a record of the population counts over the run, a record of the system state over the run, or both.

class viridicle.FullyConnectedGeography(sites, rules: Union[numpy.ndarray, Sequence[str]], generator: Optional[Union[int, numpy.random._generator.Generator]] = None, num_states: Optional[int] = None)¶

This is a geography for a fully-connected graph. All vertices are connected to every other vertex in the graph.

Parameters

sites (int or numpy.ndarray) – The current state of the system. If an integer, a new graph of that size is randomly created.
rules (list or numpy.ndarray) – Rules for the system transition. This can be provided either as a 4-dimensional numpy.ndarray where entry rules[i, j, k, l] gives the probability of the transition (i,j)->(k,l) in a single time step, or it can be provided as a list of strings giving transition rules. See the add_rule method for how these strings are interpreted and converted into an array.
generator (optional, int or numpy.random.Generator) – Random number generator. If an integer is provided, a new generator is created using that number as the seed for a default numpy random number generator.
num_states (optional, int) – Number of possible states in the system. This is only needed if you are specifying your rules as a list of strings.

add_rule(rule: str)¶

Adds a transition rule. Rules are expected to be strings of the form:

"i,j->k,l@r"

Where i, j, k, and l are integers giving a state, and r is a float giving the transition probability in a time step. A wildcard “*” is also allowed, but only one wildcard is allowed on either side of the ->, and is assumed to represent the same value on both sides - so, for example, if our system has two states, and we are provided the rule:

"*1->*[email protected]"

This is interpreted as the pair of rules:

"01->[email protected]",
"11->[email protected]"

Parameters: rule (str) – Rule to be added.

decode(sites: numpy.ndarray) → numpy.ndarray¶

Decodes an array returned from the C layer back to the system state.

Parameters: sites (numpy.ndarray) – The array to be decoded.
Returns: The numpy.ndarray.

encode() → Dict¶

Encodes the graph to a dictionary of parameters to be passed to the C layer. The dictionary for FullyConnectedGeography s will include only the keys ‘graph_type’ and ‘sites’.

Returns: The parameter dictionary.

property num_directed_edges: int¶: The number of directed edges in the system.

property num_sites: int¶: The number of sites in the system.

property num_states: int¶: Number of possible system states.

run(elapsed_time: Optional[float] = None, num_steps: Optional[int] = None, report_every: Optional[float] = None, return_counts: bool = True, return_sites: bool = False, allow_diffusion_trick: bool = True)¶

Runs the system for a specified amount of time using the Gillespie algorithm. Depending on the choice of parameters, may return a numpy.ndarray containing the counts of each site state at every reporting interval, and/or a numpy.ndarray containing the entire system at each reporting interval.

The user may specify either the amount of time to run the system, or the number of steps, but may not specify both.

Parameters

elapsed_time (optional, float) – Amount of time to run the system.
num_steps (optional, int) – Number of steps to run the system. May be specified in place of elapsed_time.
report_every (optional, float) – How often to record telemetry. If not set, return only the initial and final states. Is interpreted as either time or number of steps, depending on which of elapsed_time or num_steps is set.
return_counts (bool) – Whether to return population counts at every reporting interval. Default True.
return_sites (bool) – Whether to return the full sites array at every reporting interval. Default False.
allow_diffusion_trick (bool) – Whether to allow the use of the diffusion trick. This reduces runtime, but can cause very slight inaccuracy in the model if the diffusion rate is extremely high.

Returns

Depending on parameters set, can return a record of the population counts over the run, a record of the system state over the run, or both.

class viridicle.LatticeGeography(sites: Union[Sequence[int], numpy.ndarray], rules: Union[numpy.ndarray, Sequence[str]], generator: Optional[Union[int, numpy.random._generator.Generator]] = None, neighborhood: Optional[numpy.ndarray] = None, num_states: Optional[int] = None)¶

This is a geography for a periodic, arbitrarily-dimensioned lattice. This consists of a collection of evenly spaced vertices, usually but not necessarily 2-dimensional. The edges are specified by a set of offsets; the default offsets are [[0, 1], [1, 0], [0, -1], [-1, 0]], meaning the horizontal and vertical neighbors, for example:

 | | | | | |
-N-N-N-N-N-N-
 | | | | | |
-N-N-N-N-N-N-
 | | | | | |
-N-N-N-N-N-N-
 | | | | | |
-N-N-N-N-N-N-
 | | | | | |
-N-N-N-N-N-N-
 | | | | | |
-N-N-N-N-N-N-
 | | | | | |

However, the user may specify a different neighborhood.

Parameters

sites (sequence of int or numpy.ndarray) – The current state of the system. If a sequence of integers is provided, a new random sites array of that shape will be created.
rules (list or numpy.ndarray) – Rules for the system transition. This can be provided either as a 4-dimensional numpy.ndarray where entry rules[i, j, k, l] gives the probability of the transition (i,j)->(k,l) in a single time step, or it can be provided as a list of strings giving transition rules. See the add_rule method for how these strings are interpreted and converted into an array.
generator (optional, int or numpy.random.Generator) – Random number generator. If an integer is provided, a new generator is created using that number as the seed for a default numpy random number generator.
num_states (optional, int) – Number of possible states in the system. This is only needed if you are specifying your rules as a list of strings.
neighborhood (optional, numpy.ndarray) – The neighborhood of each vertex. If provided, this should be a 2-dimensional array such that each row gives an offset value. If not provided, defaults to the horizontally and vertically adjacent sites.

add_rule(rule: str)¶

Adds a transition rule. Rules are expected to be strings of the form:

"i,j->k,l@r"

Where i, j, k, and l are integers giving a state, and r is a float giving the transition probability in a time step. A wildcard “*” is also allowed, but only one wildcard is allowed on either side of the ->, and is assumed to represent the same value on both sides - so, for example, if our system has two states, and we are provided the rule:

"*1->*[email protected]"

This is interpreted as the pair of rules:

"01->[email protected]",
"11->[email protected]"

Parameters: rule (str) – Rule to be added.

decode(sites: numpy.ndarray) → numpy.ndarray¶

Decodes an array returned from the C layer back to the system state.

Parameters: sites (numpy.ndarray) – The array to be decoded.
Returns: The numpy.ndarray.

encode() → Dict¶

Encodes the graph to a dictionary of parameters to be passed to the C layer. The dictionary for LatticeGeography s will include the keys ‘graph_type’, ‘sites’, and ‘neighborhood’.

Returns: The parameter dictionary.

property ndim: int¶: The dimension of the lattice.

property num_directed_edges: int¶: The number of directed edges in the system.

property num_sites: int¶: The number of sites in the system.

property num_states: int¶: Number of possible system states.

run(elapsed_time: Optional[float] = None, num_steps: Optional[int] = None, report_every: Optional[float] = None, return_counts: bool = True, return_sites: bool = False, allow_diffusion_trick: bool = True)¶

Runs the system for a specified amount of time using the Gillespie algorithm. Depending on the choice of parameters, may return a numpy.ndarray containing the counts of each site state at every reporting interval, and/or a numpy.ndarray containing the entire system at each reporting interval.

The user may specify either the amount of time to run the system, or the number of steps, but may not specify both.

Parameters

elapsed_time (optional, float) – Amount of time to run the system.
num_steps (optional, int) – Number of steps to run the system. May be specified in place of elapsed_time.
report_every (optional, float) – How often to record telemetry. If not set, return only the initial and final states. Is interpreted as either time or number of steps, depending on which of elapsed_time or num_steps is set.
return_counts (bool) – Whether to return population counts at every reporting interval. Default True.
return_sites (bool) – Whether to return the full sites array at every reporting interval. Default False.
allow_diffusion_trick (bool) – Whether to allow the use of the diffusion trick. This reduces runtime, but can cause very slight inaccuracy in the model if the diffusion rate is extremely high.

Returns

Depending on parameters set, can return a record of the population counts over the run, a record of the system state over the run, or both.

property shape: Sequence[int]¶: The shape of the lattice.

class viridicle.ArbitraryGeography(sites: networkx.classes.graph.Graph, rules: Union[numpy.ndarray, Sequence[str]], generator: Optional[Union[int, numpy.random._generator.Generator]] = None, state_key: Optional[str] = None, num_states: Optional[int] = None)¶

ArbitraryGeography works with arbitrary underlying site graphs, specified as an nx.Graph. The state of each site in the graph must be given as a property. By default this property is simply ‘state’, but it can be specified by the parameter ‘state_key’.

Parameters

sites (networkx.Graph) – The current state of the system. This must be a graph encoding the system structure.
rules (list or numpy.ndarray) – Rules for the system transition. This can be provided either as a 4-dimensional numpy.ndarray where entry rules[i, j, k, l] gives the probability of the transition (i,j)->(k,l) in a single time step, or it can be provided as a list of strings giving transition rules. See the add_rule method for how these strings are interpreted and converted into an array.
generator (optional, int or numpy.random.Generator) – Random number generator. If an integer is provided, a new generator is created using that number as the seed for a default numpy random number generator.
num_states (optional, int) – Number of possible states in the system. This is only needed if you are specifying your rules as a list of strings.
state_key (optional, str) – The property of the nodes that specifies the starting state of the node. If this is None, then initialize the states randomly, and use ‘state’ as the state_key.

add_rule(rule: str)¶

Adds a transition rule. Rules are expected to be strings of the form:

"i,j->k,l@r"

Where i, j, k, and l are integers giving a state, and r is a float giving the transition probability in a time step. A wildcard “*” is also allowed, but only one wildcard is allowed on either side of the ->, and is assumed to represent the same value on both sides - so, for example, if our system has two states, and we are provided the rule:

"*1->*[email protected]"

This is interpreted as the pair of rules:

"01->[email protected]",
"11->[email protected]"

Parameters: rule (str) – Rule to be added.

decode(sites: numpy.ndarray) → networkx.classes.graph.Graph¶

Converts the sites numpy.ndarray used to pass the graph state to the C layer back to a networkx.Graph.

Parameters: sites (numpy.ndarray) – Array to be decoded.
Returns: The decoded networkx.Graph.

encode() → Dict¶

Encodes the graph to a dictionary of parameters to be passed to the C layer. The dictionary for ArbitraryGeography s will include the keys ‘graph_type’, ‘sites’, ‘edges’, and ‘edge_idxs’.

Returns: The parameter dictionary.

property is_directed: bool¶: Whether the graph is directed.

property nodes: networkx.classes.reportviews.NodeView¶: The nodes of the graph.

property num_directed_edges: int¶: The number of directed edges in the system.

property num_sites: int¶: The number of sites in the system.

property num_states: int¶: Number of possible system states.

run(elapsed_time: Optional[float] = None, num_steps: Optional[int] = None, report_every: Optional[float] = None, return_counts: bool = True, return_sites: bool = False, allow_diffusion_trick: bool = True)¶

Runs the system for a specified amount of time using the Gillespie algorithm. Depending on the choice of parameters, may return a numpy.ndarray containing the counts of each site state at every reporting interval, and/or a numpy.ndarray containing the entire system at each reporting interval.

The user may specify either the amount of time to run the system, or the number of steps, but may not specify both.

Parameters

elapsed_time (optional, float) – Amount of time to run the system.
num_steps (optional, int) – Number of steps to run the system. May be specified in place of elapsed_time.
report_every (optional, float) – How often to record telemetry. If not set, return only the initial and final states. Is interpreted as either time or number of steps, depending on which of elapsed_time or num_steps is set.
return_counts (bool) – Whether to return population counts at every reporting interval. Default True.
return_sites (bool) – Whether to return the full sites array at every reporting interval. Default False.
allow_diffusion_trick (bool) – Whether to allow the use of the diffusion trick. This reduces runtime, but can cause very slight inaccuracy in the model if the diffusion rate is extremely high.

Returns

Depending on parameters set, can return a record of the population counts over the run, a record of the system state over the run, or both.

viridicle.may_leonard_rules(n: int, r: int, diffusion_rate: float, empty_zero: bool = True) → numpy.ndarray¶

This constructs the rules tensor for the generalized (n, r) May-Leonard system, as defined in:

Ahmed, Debanjan, and Pleimling. “Interplay Between Partnership Formation and Competition in Generalized May-Leonard Games.” Physical Review E Vol. 87 No. 3. https://arxiv.org/abs/1303.3139

Parameters

n (int) – Number of species.
r (int) – Number of species that each species will prey on. Species k will predate on species k + 1, k + 2, …, k + r, calculated modulo.
diffusion_rate (float) – Rate of diffusion in the system.
empty_zero (bool) – If set, treat zero as empty, rather than as a distinct species. Default True.

Returns

A rules numpy.ndarray suitable for use in a Geography.

viridicle API¶

Viridicle

Navigation

Related Topics