ARCADE

Agent-based model of heterogeneous cell populations in dynamic microenvironments

ARCADE v2 is licensed under GPL 3. ARCADE v3+ is licensed under BSD 3-Clause.

---

• Code structure overview
• Building from source
• Running the code
• Setup file structure
• Snapshot file structure

---

Code structure overview

The src directory contains all source files for the model. The test directory contains all files for testing. The docs directory contains documentation.

arcade-X.X.X.jar is a compiled jar of the model, with the required library MASON included. Compiled jars for each release are included as a release asset.

Building from source

The model can be built from source using Gradle.

To build, use:

$ ./gradlew build

The build command will also output a command in the form:

$ docker build --build-arg VERSION=X.X.X -t arcade:X.X.X .

which can be used to build a Docker image from the compiled jar.

Documentation can be regenerated using:

$ ./gradlew javadoc

Running the code

The model can be run directly through command line, with or without real time visualization. Note that running the model with visualization is significantly slower than without visualization.

When using command line, first navigate to the directory containing the jar. Then:

$ java -jar arcade-X.X.X.jar potts XML PATH [(-v|--vis)] [--loadpath] [(-c|--cells)] [(-l|--locations)]

    XML
        Absolute path to setup XML
    PATH
        Absolute path for snapshot JSON
    [(-v|--vis)]
        Flag for running with visualization
    [--loadpath]
        Path prefix for loading files
    [(-c|--cells)]
        Flag for loading .CELLS file
    [(-l|--locations)]
        Flag for loading .LOCATIONS file

🔸 Example: Running model from command line

$ java -jar arcade.jar potts /path/to/setup.xml /path/to/output/

🔸 Example: Running model from command line with interactive visualization

$ java -jar arcade.jar potts /path/to/setup.xml /path/to/output/ --vis

🔸 Example: Running model from command line using loaded files

$ java -jar arcade.jar potts /path/to/setup.xml /path/to/output/ --loadpath /path/to/load/files --cells --locations

Setup file structure

ARCADE uses a setup file that describes the setup of the simulations, agents, and environment.

🔸 Read the setup files documentation for details on each section

Snapshot file structure

The models saves simulation snapshots to .json files, which describe the simulation and agents. Values in [ALL CAPS] are replaced with simulation values. Each simulation series produces a single overview file, and a number .CELLS/.LOCATIONS snapshots determined by the total number of simulation ticks and the snapshot interval.

Simulation series overview

The basic structure of the overview file is:

{
  "version": "[VERSION NUMBER]",
  "conversions": {
    "DS": [DS],
    "DT": [DT]
  },
  "ticks": [TICKS],
  "size": {
    "length": [LENGTH],
    "width": [WIDTH],
    "height": [HEIGHT],
    "margin": [MARGIN]
  },
  "populations": {
    "[POPULATION_ID]": {
      "CODE": [CODE],
      "PADDING": [PADDING],
      "INIT": [INIT],
      "[PARAMETER]": [PARAMETER VALUE],
    ...
      "[MODULE]/[PARAMETER]": [PARAMETER VALUE],
    ...
    },
    ...
  },
  "potts": {
    "[PARAMETER]": [PARAMETER VALUE],
    ...
    "[TERM]/[PARAMETER]": [PARAMETER VALUE],
    ...
    "[TERM]/[PARAMETER]:[TARGET]": [PARAMETER VALUE],
    ...
  }
}

Simulation .CELLS snapshot

The .CELLS snapshot file includes details about each cell agent. This file can be used to as initial conditions by loading with --cells.

[
  {
    "id": [ID],
    "parent": [PARENT ID],
    "pop": [POPULATION CODE],
    "age": [AGE],
    "divisions": [DIVISION],
    "state": [STATE],
    "phase": [PHASE],
    "voxels": [NUMBER OF VOXELS],
    "criticals": [[CRITICAL VOLUME], [CRITICAL HEIGHT]]
  },
  ...
]

Simulation .LOCATIONS snapshot

The .LOCATIONS snapshot file file includes details about each cell agent location. This file can be used to as initial conditions by loading with --locations.

[
  {
    "id": [ID],
    "center": [[CENTER_X], [CENTER_Y], [CENTER_Z]],
    "location": [
      {
        "region": [REGION],
        "voxels": [
          [[X], [Y], [Z]],
          ...
        ]
      },
      ...
    ]
  },
  ...
]