Home

PISKaS

Parallel Implementation of a Spatial Kappa Simulator, based on KaSim v3.5, is a stochastic simulator for rule-based models. With PISKaS you can create compartments connected by links, and create transports instructions to move agents among compartments. Transport is especially useful when you have a non-homogeneous space. PISKaS is highly scalable due to its MPI implementation, which allows you to create several compartments and run your simulation on many computational cores.

New functionalities with regard to KaSim:

Compartment:

For example, to create a compartment of name compartmentA and volume 1 we write

%compartment: 'compartmentA' 1

and a matrix of 4x4 and each compartment of volume 1.5

%compartment: 'compartmentA' [4][4] 1.5

Link:

A link is a connection among two compartments, and it can be unidirectional or bidirectional. To set an unidirectional link (where only the agents present in 'compartmentA' can travel to 'compartmentB'), we write

%link: 'link_name' 'compartmentA' -> 'compartmentB'

We could define a time delay using $ float like

%link: 'link_name' 'compartmentA' -> 'compartmentB' $ 1

We can assume the delay time among compartment as the travel time. To set a bidirectional link we write

%link: 'link_name' 'compartmentA' <-> 'compartmentB' $ 1

where agents in both compartments can move in any direction.

*The unit of time is arbitrary and related to your model description

Transport:

The transport defines the rate of agents per unit of time traveling inside a link. To set a rate of 1.5 time units for an agent 'agentA()' in a link called 'link_name' we write:

%transport: 'link_name' agentA() @ 1.5

We could specify if the agent must be transported without linked agents or transported with connected agents without specifying which ones. For example

%transport: <move-join> 'link_name' agentA() @ 0.2 and

%transport: <move-free> 'link_name' agentB() @ 0.7

define that agentA will move with any agent join to it and agentB will separate from any other agent and move alone. If you don't use the <move-join> or <move-free> options, the default is <move-join>.

Use:

The use instruction define the compartment that will be used and set the initial conditions of it. If we want to initialize a compartment, we write

%use: 'compartmentA'
%init: 100 agentA() #define the number of agents

where we initialize the compartmentA with 100 agents of name 'agentA()'. The instruction %init: must go immediately after the instruction %use:.

If the agents are initialized with no states in its sites, the default state will be the first defined state. For example:

%agent: person(c~S~I)
%use: 'compartment1'
%init: 300 person()
%use: 'compartment2'
%init: 500 person()

will create 300 agents called 'person' in state 'S', the first defined state, in the first compartment and 500 agents in the same configuration but in the second compartment.

Fixed rates in rules

If you want to fix a rate, i.e., you don't want it depends on the volume of a compartment, you use @*, for instance

'ruleName' agentA(),agentB() -> agentC() @* 1.5

will fix the rate of this rule at 1.5, independently of the size of the compartment.

Example

Here we present a little and simple example of PISKa. It represents how an infection spreads in a human population. This model help to understand how to implement something in PISKaS. For a complete model, visit the folder PISKaS/models/predator/

# We create an agent person with a site 's' (it can be any letter) with states
# S (susceptible) and I (infected) 
%agent: person(s~S~I)

# We create 2 cities, the first with 1 volume units and the second with 2 
# volume units.
%compartment: 'cityA' 1 
%compartment: 'cityB' 2

# Here we create a bidirectional connection between cityA and cityB, with 
# delay time of 1 time units
%link: 'highway' 'cityA' <-> 'cityB' $1

# We define which agent can move between cities and how often. In this case 
# all agents can travel between cityA and cityB through the link 'highway',
# with a rate of 0.01 time units
%transport: 'highway' person(s~S) @ 0.01
%transport: 'highway' person(s~I) @ 0.01

# Kappa rules
# We define that, when 2 person meet, one in state 'S' and other in state 'I',
# then the person in state 'S' will become 'I' with a rate of 0.001 time units.
# Without `%use:` above the Kappa rule, this is apply to both compartments.
'contact1' person(s~S), person(s~I) -> person(s~I), person(s~I) @ 0.001

# Now we initialize the cities
# First cityA, with 1000 healthy people and 1 infected
%use: 'cityA'
%init: 1000 person(s~S)
%init: 1 person(s~I)

# Now the cityB, with 1500 healthy people and no one infected
%use: 'cityB'
%init: 1500 person(s~S)

#And finally we define the output variables (we define `%use:` to apply the
#subsecuent statements to all compartments)
%use: 
%obs: 'person_S' person(s~S)
%obs: 'person_I' person(s~I)

To run this simulation we execute:

mpirun -n 2 PISKaS -i simple_example.cka -t 100 -p 100 -sync-t 1

where -n 2 is the number of compartments (and processors where they will be run), -i simple_example.cka is the input file that we called 'simple_example.cka', -t 100 is the simulation time, -p 100 is the number of points that will be stored in the output file and -sync-t 1 is the synchronization frecuency among compartments.