Overview of the Configuration Files

Any simulation requires some prior settings to be defined. For dynamics, these settings are given in two files in the configuration directory. These files are:

  • The inputs.yml file

  • The ode.py file

While the ODE’s of the dynamical system to be simulated are given in ode.py, the general parameters of the simulation are given in inputs.yml. We now look at each of these files in detail.

The inputs.yml file

The inputs.yml file determines general settings governing the simulation such as the parameters, initial conditions, timesteps and duration. An example of the file is as follows:

 1family: 'ode'
 2
 3ode_system: 'fhn'
 4
 5parameters:
 6  a: 
 7    min: -1.0
 8    max: 1.0
 9    default: 0.7
10  b: 
11    min: 0.0
12    max: 1.0
13    default: 0.8
14  c:
15    min: 0.0
16    max: 20.0
17    default: 12.5
18
19initial_conditions:
20  x: 
21    min: -5.0
22    max: 5.0
23    default: 0.1
24  y:
25    min: -5.0
26    max: 5.0
27    default: 0.1
28
29time:
30  ti: 0.0
31  tf: 1000.0
32  dt: 0.01
33  tr: 0.8

We now discuss each of the entry in the file.

The family key

The family key determines which class of system (maps, ode’s, etc.) is being solved. Therefore, each inputs.yml file must have a family key. As of now, the only valid value for it is ode. In future, we plan to add other types of families for maps, networks and other types of differential equations.

Depending on the value of the family key, the other contents of the input.yml file are determined.

The ode family

If the family is ode, then the inputs.yml file must contain the following keys.

  1. ode_system: It determines the set of differential equations being used. The value should be a user-defined name which has a corresponding entry in the ode.py file (discussed later in the document).

  2. parameters: This defines the parameters used in the system of ODE’s. It lists the variables associated with the parameters and also declares the minimum, maximum and default values for each variable.

  3. initial_conditions: This defines dynamical variables as well as their initial values in the system of ODE’s. Similar to the parameters, the minimum, maximum and the default values of the dynamical variables are declared.

  4. time: This contains time related configurations. It contains: ti and tf which give initial time of simulation. The time-step of the simulation is given by dt; and the transience is given by tr. Note that tr gives the fraction of time-period tf-ti that will be considered transience and will not be written in the timeseries.

The ode.py file

The ode.py file defines the exact system of ODE’s to be simulated. The file contains the following functions:

  1. The ode(t, x, p, type) function selects the system of ODE based on the type input and evaluates it for parameter set p at the dynamical variables defined by x. The argument type take the same value as ode_system in the inputs.yml file.

     4def ode(t, x, p, type):
 5    """Selects the system of ODE's to be simulated based on the 'type'
 6    provided and evaluates it at a given time, for a given point in the phase
 7    space and for a given set of parameters.
 8
 9    Args:
10        t (float): Time at which the system of ODE is to be evaluated
11        x (array of floats): Coordinates of the points in phase space at which 
12            the system of ODE is to be evaluated
13        p (dict of floats): Dictionary with parameter names and values at which 
14            the system of ODE is to be evaluated
15        type (string): Name of the system of ODE to be evaluated. There must be
16            a function corresponding to this name defined later
17
18    Returns:
19        array of floats: Value of the evaluated system of ODE's
20    """
21
22    if type == 'fhn':
23        return fhn(x, p)
24    elif type == 'resource':
25        return resource(x, p)
26    else:
27        sys.exit("Unknown name of system of ODE's")

  2. Similarly, the jacobian(t, x, p, type) function selects the Jacobian of the system based on the type input and evaluates it for parameter set p at the dynamical variables defined by x. The argument type take the same value as ode_system in the inputs.yml file.

    29def jacobian(t, x, p, type):
30    """Selects the Jacobian for the 'type' of system of ODE's and evaluates it
31    at a given time, for a given point in the phase space and for a given set 
32    of parameters.
33
34    Args:
35        t (float): Time at which Jacobian is to be evaluated
36        x (array of floats): Coordinates of the points in phase space at which 
37            Jacobian is to be evaluated
38        p (dict of floats): Dictionary with parameter names and values at which 
39            Jacobian is to be evaluated
40        type (string): Name of the system for which Jacobian to be evaluated. 
41            There must be a function corresponding to this name defined later
42
43    Returns:
44        array of floats: Value of the evaluated Jacobian
45    """
46
47    if type == 'fhn':
48        return jac_fhn(x, p)
49    elif type == 'resource':
50        return jac_resource(x, p)
51    else:
52        sys.exit("Unknown name of system of ODE's")

  3. Finally, the file contains the list of systems of ODE’s as functions. Note that, for each system of ODE’s, the correcponding Jacobians are also defined.

     54# ODE Systems
 55
 56def fhn(x, p):
 57    """ODE's defining the FitzHugh-Nagumo system
 58
 59    Args:
 60        x (array of floats): length 2 describing variables 'x' and 'y'
 61        p (dict of floats): contains keys describing parameters 'a', 'b', 'c'
 62
 63    Returns:
 64        array of floats: Value of the function
 65    """
 66    
 67    assert len(x) == 2
 68
 69    return np.array([
 70        x[0] - (x[0]**3)/3.0 - x[1] + 0.5,
 71        (x[0] + p['a'] - p['b']*x[1])/p['c']
 72    ])
 73
 74def resource(x, p):
 75    """ODE's defining a simple resource dynamics
 76
 77    Args:
 78        x (array of floats): length 1 describing variables 'x'
 79        p (dict of floats): contains keys describing parameters 'r' and 'p'
 80
 81    Returns:
 82        array of floats: Value of the function
 83    """
 84
 85    assert len(x) == 1
 86
 87    return np.array([
 88        p['r']*x[0]*(1.0-x[0]) - p['p']*x[0]
 89    ])
 90
 91# Jacobians
 92
 93def jac_fhn(x, p):
 94    """Jacobian of the FitzHugh-Nagumo system
 95
 96    Args:
 97        x (array of floats): length 2 describing variables 'x' and 'y'
 98        p (dict of floats): contains keys describing parameters 'a', 'b', 'c'
 99
100    Returns:
101        array of floats: Value of the Jacobian
102    """
103    
104    assert len(x) == 2
105
106    return np.array([
107        [
108            1 - x[0]**2,
109            -1
110        ],
111        [
112            1/p['c'],
113            p['b']/p['c']
114        ]
115    ])
116
117def jac_resource(x, p):
118    """Jacobian of the resource dynamics model
119
120    Args:
121        x (array of floats): length 1 describing variables 'x'
122        p (dict of floats): contains keys describing parameters 'r' and 'p'
123
124    Returns:
125        array of floats: Value of the Jacobian
126    """
127
128    assert len(x) == 1
129
130    return np.array([
131        [
132            p['r'] - 2*p['r']*x[0] - p['p']
133        ]
134    ])