Home » Software » AcCoRD (Actor-based Communication via Reaction-Diffusion) » How to Use AcCoRD » AcCoRD Configuration

AcCoRD Configuration

This page presents an overview of the AcCoRD configuration file structure and how to preview environments in MATLAB. You can refer to the How to Use AcCoRD page to discuss the entire workflow for using accord. Once you have prepared a configuration file, you can refer to the How to Run AcCoRD page to run the simulation.

Every simulation in AcCoRD relies on a single configuration file that defines the simulation environment. Configuration files should be kept in the AcCoRD “config” directory. A number of sample configuration files are included with the AcCoRD download. Modifying an existing configuration is the easiest way to start setting up your own simulation. However, since AcCoRD is a simulation sandbox, the sample files cannot cover all possible configurations. So, this section summarizes the configuration file format. For a detailed description of the structure of a configuration file, including a listing of all possible configuration parameters, please refer to the AcCoRD Configuration Parameters page.

As an alternative reference, the file “HOWTO_DEFINE_CONFIG.txt” in the AcCoRD download also describes all configuration options.

AcCoRD Configuration File Format

AcCoRD configuration files are written in the JSON (JavaScript Object Notation) interchange format. JSON uses a simple structure to store data that is easy to read and modify. You do not need to read all the details of JSON to modify JSON-format files, but here are a few things to keep in mind:

  • JSON objects are set of name/value pairs that are enclosed inside curly braces. Each AcCoRD configuration has a single parent object.
  • The format for a name/value pair is (including quotation marks) “Name of pair”: VALUE, where VALUE can be a string (inside quotes), an integer, a double, another object (inside curly braces), or an array.
  • Multiple name/value pairs inside the same object are separated by commas.
  • in AcCoRD, placing a comma after the last name/value pair in an object, or writing a decimal number without a leading digit (e.g., .25 for 0.25) will result in an error. Such errors will print out the configuration file from the point where the first error occurred.
  • AcCoRD is case sensitive for field names.
  • The ordering of fields within a given object does not matter.
  • There is no formal commenting mechanism. However, additional string values can be included to behave as comments. This is done throughout the sample configuration files via the “Notes” field.

Overall Structure of AcCoRD Configuration

The structure of an AcCoRD configuration file is as follows (with sample values):

{
    "Output Filename": "my_output",
    "Warning Override": false,
    "Simulation Control": {},
    "Chemical Properties": {},
    "Environment": {}
}

These name/value pairs are used as follows:

  • “Output Filename” (optional) – Prefix for the output data files that will be created by the simulation. Seed information will be appended to this prefix. Default value is “test”.
  • “Warning Override” (optional) – Switch to ignore configuration warnings (when true) and proceed with simulation without pausing. Default value is false. When false, the simulation will pause if any parameters are needed and default values are assigned (either because they were missing or defined incorrectly). Whether true or false, all warning messages will be printed to the command line.
  • “Simulation Control” – An object containing global simulation parameters. It should not be empty as shown above!
  • “Chemical Properties” – An object containing molecule parameters, including chemical reaction specifications. It should not be empty as shown above!
  • “Environment” – An object specifying the regions and actors in the simulation environment. It should not be empty as shown above!

See the AcCoRD Configuration Parameters page for more details on defining the “Simulation Control”, “Chemical Properties”, and “Environment” objects.

Visualizing an Environment

You can test the environment of a configuration file before simulating it. AcCoRD includes a MATLAB utility for drawing the actors and regions a simulation environment. This utility does not do a comprehensive testing of parameter validity, but is useful for a visual confirmation of what the environment will look like. MATLAB version R2015a or newer is recommended.

The “main” function for this utility is accordEmptyEnvironment.m, and it is not recommended that you call it directly. The function requires non-trivial input arguments to control how the environment and its contents are drawn. However, a sample wrapper function, accordEmptyEnvironmentWrapper.m, is provided that prepares all of the necessary inputs. You should make a copy of the wrapper function and then modify it for your environment. The comments in the wrapper describe all of the arguments that are passed to accordEmptyEnvironment and what other files you can refer to for information on modifying the arguments.

Here is a sample environment drawing:

Drawing of an environment
Drawing of a sample complex environment, as generated by the utility accordEmptyEnvironment. The configuration file for this environment and the wrapper file to plot it can be found on the AcCoRD Examples page.

The Next Step

When your configuration file is ready, you can run AcCoRD.