Skip to content

Getting started#

Table of Contents#

Installation and environment set up#

Please note that for development, we suggest using Poetry for dependency management and packaging. Instructions for setting up the Python environment with Poetry are in the section Reference.

0. Pre-installation Virtual Environments with venv (Optional):#

If you wish to create an easy to use virtual environment to install radCAD inside of, please use the built in venv package [see: documentation about venv].

Create a virtual environment:

$ python3 -m venv venv

Activate an existing virtual environment (Unix/macOS):

$ source venv/bin/activate

Activate an existing virtual environment (Windows):

$ source venv\Scripts\activate

1. Installation:#

Requires >= Python 3.8

Install Using pip

$ pip install radCAD

2. Install Python dependencies inside virtual environment#

pip install -r requirements.txt

Jupyter Notebooks#

Assuming that the ipykernel has been installed together with the other dependencies from requirements.txt (step 2)

ipython kernel install --user --name=radcad_kernel

First model:#

We refer to the section Examples to see various models and references to tutorials.

Run predator-prey-sd.py to check if radCAD has been successfuly installed. This is a script version of the Jupyter Notebooks model predator-prey-sd.ipynb that is refered to in the section Examples.

cd examples/predator_prey_sd
python predator-prey-sd.py

Did you get the expected output, as follows?

The final sizes of the populations are, prey: 3068.0 and predator: 215.0.

Elements of the model#

This section contains high level information about the model. For more details please consult the following sections: Features for information organised by model functionality, Model Architecture for more information about the model architecture, and Examples to see some ways how the model can be applied.

Main classes#

radCAD provides the following classes:

  1. A system is represented in some form as a Model
  2. A Model can be simulated using a Simulation
  3. An Experiment consists of one or more Simulation
  4. An Experiment or a Simulation is run by the Engine

So, the hierarchy is as follows Model > Simulation > Experiment > Engine.

from radcad import Model, Simulation, Experiment

model = Model(initial_state=initial_state, 
              state_update_blocks=state_update_blocks, 
              params=params)
simulation = Simulation(model=model, timesteps=100_000, runs=1)

result = simulation.run()
# Or, multiple simulations:
# experiment = Experiment([simulation_1, simulation_2, simulation_3])
# result = experiment.run()

df = pd.DataFrame(result)

The typical layout of the radCAD model elements:#

Modelling

  1. System parameters
  2. State variables (including initial state)
  3. Policy functions
  4. State update functions
  5. Partial state update blocks

Simulation

  1. Simulation configuration parameters
  2. Model
  3. Simulation
  4. Execute the simulation
  5. Analysis

If you are familiar with cadCAD, you might notice that the classes provided by radCAD are a bit different, and so is the typical layout. Learn more about cadCAD Compatibility.