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 move to the directory where you want Cadmium 2 to be located. Then, insert the following commands:

git clone https://github.com/SimulationEverywhere/cadmium_v2.git
cd cadmium_v2
git submodule update --init --recursive

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 these lines in the CMakeLists.txt of your project:

include_directories(<RELATIVE_PATH_TO_CADMIUM_2_FROM_YOUR_PROJECT>/include)
include_directories(< RELATIVE_PATH_TO_CADMIUM_2_FROM_YOUR_PROJECT>/json/include)

Running Examples

The Cadmium library provides a set of examples in the example directory. To build all the examples, open a terminal INSIDE the Cadmium 2 folder and insert the following commands in your terminal:

mkdir build
cd build
cmake ..
make all

Now, there will be a new folder bin with one program for each example (main_*). If your machine can run parallel simulations (check this page to find out how), you also will find programs starting with parallel_main_* that executes in parallel. Finally, if you have installed all the additional dependencies for developers (check this page to find out how), you will also find an executable 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 (GPT) DEVS model. This is a well-known example in the DEVS community. Page 3 of this Wiki explains this model and 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

Experimental Frame-Transducer DEVS model. This is a variant of the GPT model with different structure but the exact same behavior. Page 3 of this Wiki explains this model and elaborates on implementation and usage details of this example.

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

./main_efp

main_devstone

main_asymm_sir

main_grid_sir

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. To do so, you need to install Boost in your machine (see Page 1). To run all the tests, open a terminal INSIDE the Cadmium 2 folder and insert the following commands in your terminal:

mkdir build
cd build
cmake ..
make all
ctest

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

If you are using the main or devel branches, ALL THE TEST MUST PASS. If not, please open an issue in this repository with all the information required to reproduce your environment. We will try to detect and fix the problem as soon as possible.