2. Installation

Cadmium 2 is a header-only library. This means that you don't need to compile nor install it in your machine. You just have to include the header files to your project. To "install" Cadmium, you just have to download this repository and all its submodules on your local machine using git. Open a terminal (a Cygwin terminal in Windows) and insert the following commands:

cd <WORKSPACE>  # Set the terminal working directory to taste
git clone https://github.com/SimulationEverywhere/cadmium_v2.git  # Download Cadmium 2
cd cadmium_v2  # move to the parent folder of Cadmium 2
git submodule update --init --recursive  # Download the git submodules of Cadmium 2

And that's it: you already have everything you need for using Cadmium 2. Now, you just have to include the include/ directory of Cadmium 2 to your project. If you use CMake to build your Cadmium models (we highly recommend you to use it), you just have to include this directory in the CMakeLists.txt of your project:

include_directories(<RELATIVE_PATH_TO_WORKSPACE_FROM_YOUR_PROJECT>/cadmium_v2/include)

If you want to develop Cell-DEVS models, you will need to include additional directory to help Cadmium to parse your JSON configuration files. Again, if you use CMake, you just have to include this directory in the CMakeLists.txt of your project:

include_directories(<RELATIVE_PATH_TO_WORKSPACE_FROM_YOUR_PROJECT>/cadmium_v2/json/include)

Testing the Software

We use GitHub Actions, a tool for Continuous Integration (CI), to check that the devel and main branches pass all the tests automatically. There you can check whether the code is stable or not. You can check which commits pass the tests in the Actions tab of this repository. However, you may want to run some tests to make sure that everything works in your machine as expected. You have two options:

# Make sure that the working directory of the terminal is the cadmium_v2 folder
mkdir build
cd build
cmake ..  # It generates the Makefile for the test and examples
make all  # This command compiles the tests and examples
ctest     # It runs all the tests

After running the tests, the output of your terminal should show something like this:

Test project <WORKSPACE>/cadmium_v2/build
    Start 1: test_celldevs_queue
1/6 Test #1: test_celldevs_queue ..............   Passed    0.12 sec
    Start 2: test_atomic
2/6 Test #2: test_atomic ......................   Passed    0.08 sec
    Start 3: test_coupled
3/6 Test #3: test_coupled .....................   Passed    0.09 sec
    Start 4: test_port
4/6 Test #4: test_port ........................   Passed    0.08 sec
    Start 5: test_devstone
5/6 Test #5: test_devstone ....................   Passed    9.48 sec
    Start 6: test_grid_scenario
6/6 Test #6: test_grid_scenario ...............   Passed    0.07 sec

100% tests passed, 0 tests failed out of 6

Running Examples

The Cadmium library provides a set of examples in the example directory.

# Make sure that the working directory of the terminal is the cadmium_v2 folder
mkdir build
cd build
cmake ..  # It generates the Makefile for the test and examples
make all  # This command compiles the tests and examples

Now, there will be a new folder bin with one program for each example (main_*) and for each test (test_*). To run any of these examples, you just need to open a new terminal in the bin folder and execute the binary that corresponds to the example you want to run. We next explain how to execute these examples.

main_gpt

Generator-Processor-Transducer DEVS model. This is a well-known example in the DEVS community. [Page 3](3. Examples of DEVS Models) of this wiki elaborates on implementation and usage details of this example.

If you want to run the main_gpt example, open a terminal in the bin folder and insert the following command:

./main_gpt

main_efp

main_devstone

main_asymm_sir

main_grid_sir