Skip to main content Skip to navigation

School of Engineering

AcCoRD Configuration Parameters

This page describes the AcCoRD configuration parameters. Many of the options are labelled as one of the following:

  • usually define - The parameter has a default value but it should generally be defined by the configuration. A warning will appear if it is not defined (or is defined improperly). It is recommended to fix warning cases because they might prevent importing the simulation output into MATLAB.
  • optional - The parameter has a default value but it is only needed under certain conditions. A warning will appear if it is not defined and should have been, or if it is defined but not needed. It is recommended to fix warning cases because they might prevent importing the simulation output into MATLAB.

If a parameter has neither label, then it should always be defined. An error will appear if it is not defined. For instructions on using an AcCoRD configuration file to run a simulation, please refer to the How to Use AcCoRD page. For sample complete configuration files, please refer to the AcCoRD Examples page. For more information on how these parameters are used within a simulation, please refer to the journal paper on the AcCoRD Publications page.

Overall Structure of AcCoRD Configuration Parameters

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" (usually define) - 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" (usually define) - 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! For details, see below.
  • "Chemical Properties" - An object containing molecule parameters, including chemical reaction specifications. It should not be empty as shown above! For details, see below.
  • "Environment" - An object specifying the regions and actors in the simulation environment. It should not be empty as shown above! For details, see below.

See below for more about configuring the Simulation Control, Chemical Properties, and Environment objects.

Simulation Control

The "Simulation Control" object is structured with (some or all of) the following fields (with sample values):

"Simulation Control": {
    "Number of Repeats": 1,
    "Final Simulation Time": 0.1,
    "Global Microscopic Time Step": 1e-4,
    "Random Number Seed": 1,
    "Max Number of Progress Updates": 100
    "Small Subvolumes at Hybrid Interface?": true,
    "Max Intrastep Micro to Meso Distance": 10e-6
}

These name/value pairs are used as follows:

  • "Number of Repeats" (usually define) - The number of times that the simulation will be repeated (i.e., the number of realizations) in one execution. Default value is 1.
  • "Final Simulation Time" (usually define) - The simulated time (in seconds) when the simulation will stop. Not really optional, since the default value is 0. This is not the same as the simulation run time, which is the time it takes for a computer to simulate the system.
  • "Global Microscopic Time Step" (usually define) - The time step for the microscopic regime (in seconds), which is the granularity of a microscopic simulation. Not really optional if there are any microscopic regions, since the default value is 0.
  • "Random Number Seed" (optional) - Integer used to initialize the random number generator. If you want to aggregate simulation results into a single output, then the different simulations will only be different if they were run with different seeds. However, this parameter is optional because the seed value can be entered via the command line. Default value is 1.
  • "Max Number of Progress Updates" (usually define) - Integer defining the maximum number of updates on the simulation progress. Updates print the index of the current repeat/realizations being simulated and an estimate of the remaining simulation time. There is no more than one update per realization. Default value is 10.
  • "Small Subvolumes at Hybrid Interface?" (optional) - Switch to define the transition rules used at the interface between microscopic and mesoscopic regimes (i.e., the hybrid interface). The rules can either assume that mesoscopic subvolumes at the interface are small (and therefore on the scale of movement in the microscopic regime), or that they are relatively large. This switch is only needed if there is at least one microscopic region and one mesoscopic region. Default value is false. See the journal paper on the AcCoRD Publications page for more about the ramifications of this parameter.
  • "Max Intrastep Micro to Meso Distance" (optional) - Maximum distance (in meters) that a microscopic molecule must be within, both before and after a diffusion step, to assume that it could have entered and exited the mesoscopic regime within the time step. This distance is only needed if there is at least one microscopic region and one mesoscopic region. Default value is 0. See the journal paper on the AcCoRD Publications page for more about the ramifications of this parameter.

Chemical Properties

The "Chemical Properties" object in an AcCoRD configuration file is structured as follows (with sample values):

"Chemical Properties": {
    "Number of Molecule Types": 1,
    "Diffusion Coefficients": [1e-9],
    "Global Flow Type": "Uniform",
    "Global Flow Vector": [1e-3, 0, 0],
    "Does Molecule Type Flow?": [true],
    "Chemical Reaction Specification": []
}

These name/value pairs are used as follows:

  • "Number of Molecule Types" (usually define) - The number of types of molecules that exist in the environment. Default value is 1.
  • "Diffusion Coefficients" (usually define) - Array of global diffusion coefficients (in meters squared per second) for each type of molecule, each separated by a comma. Length of the array should be equal to the "Number of Molecule Types". Default value for each coefficient is 0.
  • "Global Flow Type" (usually define) - String to indicate the default type of flow applied to every region. Possible values are "None" and "Uniform". If "Uniform", then flow is steady and uniform. Default type is "None".
  • "Global Flow Vector" (optional) - Array defining the global flow parameters. Only needed if "Global Flow Type" is not "None". If "Global Flow Type" is "Uniform", then array should have length three and define the flow along the (x,y,z) directions in meters per second.
  • "Does Molecule Type Flow?" (optional) - Array of switches indicating whether each type of molecule follows the global flow. Only needed if "Global Flow Type" is not "None" and some molecule type does not follow the global flow. Length of the array should be equal to the "Number of Molecule Types". Default value for each molecule type is true.
  • "Chemical Reaction Specification" (usually define) - Array containing details of all chemical reactions in the environment. Each reaction has its own object within the array. Default value is an empty array.

If the "Chemical Reaction Specification" array is not empty, then its objects are structured with (some of) the following fields (with sample values):

{
    "Label": "",
    "Is Reaction Reversible?": false,
    "Reverse Reaction Label": "Some other Reaction Label",
    "Surface Reaction?": false,
    "Surface Reaction Type": "Absorption",
    "Surface Reaction Diffusion Coefficient": 1e-9,
    "Surface Transition Probability": "Steady State",
    "Default Everywhere?": true,
    "Exception Regions": [],
    "Reactants": [0],
    "Products": [0],
    "Products Released?": [false],
    "Release Placement Type": "Leave",
    "Reaction Rate": 1,
    "Binding Radius": 1e-6,
    "Unbinding Radius": 5e-6
}

These name/value pairs are used as follows:

  • "Label" (usually define) - A string ID for the reaction. Only needed if the reaction is reversible in order to indicate which reaction it is coupled to. Default value is an empty string.
  • "Is Reaction Reversible?" (usually define) - Switch to indicate whether the reaction is reversible. Currently only used when calculating the steady state reaction probabilities of surface reactions. Default value is false.
  • "Reverse Reaction Label" (optional) - String ID "Label" of the reverse reaction. Only needed if the reaction if "Is Reaction Reversible?" is true. If not defined, then "Is Reaction Reversible?" is set to false.
  • "Surface Reaction?" (optional) - switch to indicate whether the reaction is a first order surface interaction reaction, such as absorption, desorption, or transitioning through the surface as if it were a membrane. Default value is false.
  • "Surface Reaction Type" (optional) - String to indicate the type of surface interaction reaction. Possible values are "Normal", "Absorbing", "Desorbing", "Membrane Inner", and "Membrane Outer". Only needed if "Surface Reaction?" is true. Default type is "Normal". The membrane reactions should only be assigned to surface regions that are configured as membranes. The "Membrane Inner" reaction is for molecules that transition from the side of the membrane where the surface is considered to be on the "in" side of the adjacent normal region, i.e., 2D surfaces that are to the left, down, or in directions relative to the normal region (i.e., surface is along the lower x, y, or z face of the normal region), or if the surface is the parent of the normal region. The "Membrane Outer" reaction is for molecules that transition from the side of the membrane where the surface is considered to be on the "out" side of the adjacent normal region, i.e., 2D surfaces that are to the right, up, or out directions relative to the normal region (i.e., surface is along the upper x, y, or z face of the normal region), or if the normal region is the parent of the surface.
  • "Surface Reaction Diffusion Coefficient" (optional) - Diffusion coefficient (in meters squared per second) to override the default diffusion coefficient for a surface reaction. Only relevant if "Surface Reaction?" is true. The default coefficient is the global diffusion coefficient of the reactant for an absorbing or membrane transition reaction, and that of the first product for a desorption reaction.
  • "Surface Transition Probability" (optional) - String indicating how the surface reaction probability is calculated. Only needed if "Surface Reaction?" is true and "Surface Reaction Type" is not normal. Options are "Normal", "Steady State", and "Mixed". Default value is "Normal". See the journal paper on the AcCoRD Publications page for more about the ramifications of this parameter.
  • "Default Everywhere?" (usually define) - Switch to indicate whether the reaction exists in all corresponding regions (i.e., in all surface regions for a surface reaction, or all normal regions for a non-surface reaction). Default value is true.
  • "Exception Regions" (usually define) - Array of strings to indicate the labels of regions that are exceptions to the "Default Everywhere?" value. Default is an empty array.
  • "Reactants" (usually define) - Array of non-negative integers indicating which molecules are reactants in the reaction. Length of the array should be equal to the "Number of Molecule Types". Default value for each molecule type is 0. There must be no more than two reactants for most reactions, and no more than one reactant if the reaction is surface reaction that is not "Normal". The order of the reaction (i.e., zeroth order, first order, or second order) is determined by the sum of the values in this array.
  • "Products" (usually define) - Array of non-negative integers indicating which molecules are products in the reaction. Length of the array should be equal to the "Number of Molecule Types". Default value for each molecule type is 0. All values are ignored for "Membrane Inner" and "Membrane Outer" reactions, where it is assumed that the product is the same type of molecule as the reactant.
  • "Products Released?" (optional) - Array of switches indicating whether each product molecule is detached from the surface into the adjacent normal region. Only needed if "Surface Reaction?" is true. Length of the array should be equal to the "Number of Molecule Types". Default value for each molecule type is false.
  • "Release Placement Type" (optional) - String indicating how released molecules are placed. Only needed if "Surface Reaction?" is true and at least one value in "Products Released?" is true. Length of the array should be equal to the "Number of Molecule Types". Options are "Leave", "Full Diffusion", and "Steady State Diffusion". Default value is "Leave". See the journal paper on the AcCoRD Publications page for more about the ramifications of this parameter.
  • "Reaction Rate" (usually define) - Non-negative number defining the chemical reaction rate. Units are those that are standard for each order of reaction (molecules per second per meter cubed for zeroth order, per second for first order, and meter cubed per molecule per second for second order). Default value is 0.
  • "Binding Radius" (optional) - Non-negative number defining the maximum distance (in meters) that two reactant molecules in a second order chemical reaction can be separated by at the end of a microscopic time step and still react. Only needed if the reaction is second order and can occur in a microscopic region. Default value is 0.
  • "Unbinding Radius" (optional) - Non-negative number defining the separation distance (in meters) that is applied to the products of a second order reaction. Only needed if the reaction is second order, it can occur in a microscopic region, and there are at least two products. Default value is If there are exactly two products, then they are placed along the line that joins the locations of the two reactants after they diffused. Each reaction's displacement from the reaction location is proportional to its diffusion coefficient. If there are more than two products, then each is placed in a random direction but the sum of the distances of the products from the reaction location is equal to the "Unbinding Radius".

For more information on how these parameters are used to implement chemical reactions, please refer to the journal paper on the AcCoRD Publications page.

Environment

The "Environment" object in an AcCoRD configuration file is structured as follows (with sample values):

"Environment": {
    "Subvolume Base Size": 1e-6,
    "Region Specification": [],
    "Actor Specification": []
}

These name/value pairs are used as follows:

  • "Subvolume Base Size" - Positive number defining the granularity (in meters) of the size of rectangular region subvolumes. Every rectangular region (whether microscopic or mesoscopic) is composed of square/cubic subvolumes whose length is an integer multiple of "Subvolume Base Size". This parameter is also used to define the margin of error for detecting regions that overlap incorrectly, so it is needed for any simulation. Default value is 1.
  • "Region Specification" - Array containing details of all regions in the environment. Each region has its own object within the array. A valid configuration must have at least one region. For details, see below.
  • "Actor Specification" - Array containing details of all actors in the environment, including active actors and passive actors. Each actor has its own object within the array. A valid configuration must have at least one actor (it could be active or passive). For details, see below.

See below for more about configuring the Region Specification and Actor Specification objects.

Regions

The objects in the "Region Specification" array of an AcCoRD configuration file are structured with (some of) the following fields (with sample values):

{
    "Label": "",
    "Parent label": "",
    "Local Diffusion Coefficients": [0, 0],
    "Shape": "Rectangular Box",
    "Type": "Normal",
    "Surface Type": "Outer",
    "Anchor Coordinate": [0, 0, 0],
    "Anchor X Coordinate": 0,
    "Anchor Y Coordinate": 0,
    "Anchor Z Coordinate": 0,
    "Integer Subvolume Size": 1,
    "Is Region Microscopic?": true,
    "Number of Subvolumes Per Dimension": [1, 1, 1],
    "Number of Subvolumes Along X": 1,
    "Number of Subvolumes Along Y": 1,
    "Number of Subvolumes Along Z": 1,
    "Radius": 5e-6,
    "Local Flow": [
        {
            "Is Molecule Type Affected?": [true],
            "Flow Type": "Uniform",
            "Flow Vector": [2e-3, 0, 0]
        }
    ]
}

These name/value pairs are used as follows:

  • "Label" (usually define) - A string ID for the region. Only needed if another region is nested inside this region or if an actor's shape will be defined using this region. Default is an empty string. It is recommended that non-empty Region Labels be at least 2 characters long to avoid a JSON bug that treats arrays of single-character strings as one string (which leads to errors if you try to plot the environment).
  • "Parent label" (usually define) - A string ID stating the region's parent region, such that this region is nested inside of it (and referred to as the child). Needed if this region is nested inside another region. A child region must be entirely inside its parent. Multiple generations of nesting are possible (i.e., a parent region can also have its own parent region, etc.).
  • "Local Diffusion Coefficients" (optional) - Array of local diffusion coefficients (in meters squared per second) for each type of molecule, each separated by a comma. Length of the array should be equal to the "Number of Molecule Types". Default value for each coefficient is 0. If local values are not defined, then the values specified by "Diffusion Coefficients" in the "Chemical Properties" object are used.
  • "Shape" (usually define) - String defining the shape of the region. Options are "Rectangular Box", "Sphere", and "Rectangle". Default is "Rectangular Box".
  • "Type" (usually define) - String defining the type of region. Options are "Normal", "3D Surface", and "2D Surface". Default is "Normal". A "Normal" region occupies the entirety of its volume (except where there are child regions). A "3D Surface" region is a surface to a 3D "Normal" region and a "2D Surface" is a surface to a 2D "Normal" region. For example, a normal "Rectangular Box" could have a surface "Rectangular Box" nested inside and/or a surface "Rectangle" along some or all of one of its faces. Each of the surfaces in this case should be defined as a "3D Surface".
  • "Surface Type" (optional) - String defining the type of surface. Options are "Outer", "Inner", and "Membrane". Default is "Membrane". The "Outer" and "Inner" surfaces are both one-sided and the type specifies the side. These surfaces block diffusion and can have chemical reactions occur at them. An "Inner" surface is considered to be on the "in" side of the adjacent normal region, i.e., 2D shapes that are to the left, down, or in directions relative to the 3D normal region (i.e., surface is along the lower x, y, or z face of the normal region), or if the surface is the parent of the normal region. An "Outer" surface is considered to be on the "out" side of the adjacent normal region, i.e., 2D shapes that are to the right, up, or out directions relative to the 3D normal region (i.e., surface is along the upper x, y, or z face of the normal region), or if the normal region is the parent of the surface. The "Membrane" surface is double-sided and blocks diffusion unless there is membrane reaction defining the rate at which a molecule can pass through. This parameter is only needed if the region's "Type" is "3D Surface" or "2D Surface".
  • "Anchor Coordinate" (optional) - An array with 3 numbers (in meters) that define the region's location in global space. For a rectangular region, the anchor is its corner with the smallest (X,Y,Z) coordinate. For a "Sphere", the anchor is the center. This is the default method for defining the anchor; the alternative is to define the (X,Y,Z) values individually. Default is [0, 0, 0].
  • "Anchor X Coordinate", "Anchor Y Coordinate", "Anchor Z Coordinate" (optional) - A number defining the value (in meters) of the region's location in the corresponding dimension (see "Anchor Coordinate" above). This is the alternative method for defining the anchor; the default is to define the (X,Y,Z) values in a single array. Default value is 0.
  • "Integer Subvolume Size" (optional) - Positive integer number defining the length of each individual subvolume. The actual subvolume length will be this value times "Subvolume Base Size". Only needed for rectangular regions (i.e., "Rectangular Box" and "Rectangle"). Default value is 1.
  • "Is Region Microscopic?" (optional) - Switch indicating whether a region is microscopic or mesoscopic. Only needed for rectangular regions (i.e., "Rectangular Box" and "Rectangle"), since a "Sphere" is always microscopic. Default value is false.
  • "Number of Subvolumes Per Dimension" (optional) - An array with three non-negative integers defining the total size of the region by specifying its length (in subvolumes) along each Cartesian dimension. Only needed for rectangular regions (i.e., "Rectangular Box" and "Rectangle"). This is the default method for defining the length of the region; the alternative is to define the (X,Y,Z) values individually. Default is [1, 1, 1]. A "Rectangle" region must have a single zero value for one of the dimensions.
  • "Number of Subvolumes Along X", "Number of Subvolumes Along Y", "Number of Subvolumes Along Z" (optional) - A non-negative integer defining the length of the region (in subvolumes) along the corresponding dimension. Only needed for rectangular regions (i.e., "Rectangular Box" and "Rectangle"). This is the alternative method for defining the length of the region; the default is to define the (X,Y,Z) values in a single array. Default value is 1.
  • "Radius" (optional) - A non-negative number defining the radius (in meters) of a "Sphere" region. Only needed for a "Sphere" region. Default value is the "Subvolume Base Size". Set radius to a value that is bigger than the maximum double (e.g., 1e9999) to have an unbounded region.
  • "Local Flow" (optional) - An array of objects describing exceptions to the local flow parameters. Array can be of any length but only the first exception specified for a given molecule type will be applied. Each object can have the following:
    • "Is Molecule Type Affected?" (usually define) - Array of switches whose length is equal to "Number of Molecule Types". If switch for any molecule type is true, and the current local flow exception is the first to list that molecule type, then the current exception will apply. Default value for each molecule type is false.
    • "Flow Type" (usually define) - String defining type of flow. Same possible values as "Global Flow Type" in the "Chemical Properties" object.
    • "Flow Vector" (optional) - Array defining the local exception flow parameters. Only needed if the "Flow Type" for the current exception is not "None". Same possible values as "Global Flow Vector" in the "Chemical Properties" object.

Here is a sample object for a rectangular region (with irrelevant parameters excluded):

{
    "Label": "",
    "Parent label": "",
    "Shape": "Rectangular Box",
    "Type": "Normal",
    "Anchor Coordinate": [0, 0, 0],
    "Integer Subvolume Size": 1,
    "Is Region Microscopic?": true,
    "Number of Subvolumes Per Dimension": [1, 1, 1]
}

Here is a sample object for a spherical surface region (with irrelevant parameters excluded):

{
    "Label": "",
    "Parent label": "",
    "Shape": "Sphere",
    "Type": "Surface",
    "Surface Type": "Outer",
    "Anchor Coordinate": [0, 0, 0],
    "Radius": 5e-6
}

Actors

The objects in the "Actor Specification" array of an AcCoRD configuration file are structured with (some of) the following fields (with sample values):

{
    "Is Location Defined by Regions?": false,
    "List of Regions Defining Location": [],
    "Shape": "Rectangular Box",
    "Outer Boundary": [0, 5e-6, 0, 10e-6, 0, 10e-6],
    "Is Actor Active?": true,
    "Start Time": 0,
    "Is There Max Number of Actions?": false,
    "Max Number of Actions": 100,
    "Is Actor Independent?": true,
    "Action Interval": 5e-3,
    "Is Actor Activity Recorded?": true,
    "Random Number of Molecules?": false,
    "Random Molecule Release Times?": false,
    "Release Interval": 0,
    "Slot Interval": 0,
    "Bits Random?": true,
    "Bit Sequence": [0, 1, 1, 1, 0, 0, 1, 0],
    "Probability of Bit 1": 1,
    "Modulation Scheme": "CSK",
    "Modulation Bits": 1,
    "Modulation Strength": 10,
    "Is Molecule Type Released?": [true],
    "Is Time Recorded with Activity?": false,
    "Is Molecule Type Observed?": [true],
    "Is Molecule Position Observed?": [true]
}

These name/value pairs are used as follows:

  • "Is Location Defined by Regions?" (usually define) - A switch indicating how the shape of the actor is defined. If true, then the actor will exist over the union of a set of regions. If false, then the actor will have its own shape. Default is false.
  • "List of Regions Defining Location" (optional) - An array of strings of the "Label"s of the regions whose union defines the shape of the actor. The regions can be disjoint. Only needed if "Is Location Defined by Regions?" is true. Default value is an empty array.
  • "Shape" (optional) - String defining the shape of the region. Options are "Rectangular Box", "Sphere", "Rectangle", and "Point" (however, only active actors can be defined as a point, since molecules in the space of 0 volume cannot be observed). Only needed if "Is Location Defined by Regions?" is false. Default is "Rectangular Box".
  • "Outer Boundary" (optional) - A numeric array defining the outer boundary of the actor (in meters). Only needed if "Is Location Defined by Regions?" is false. The length of the array depends on the "Shape" parameter. For "Rectangular Box" or "Rectangle", the format is [xmin, xmax, ymin, ymax, zmin, zmax]. For "Sphere", the format is [xCenter, yCenter, zCenter, radius]. The "Sphere" will be unbounded if the radius is larger than the largest double value, e.g., 1e9999 (but active actors should not be unbounded). For "Point", the format is [x, y, z]. Default value of any element is 0. An actor should be defined within the space occupied by regions. However, a passive actor is permitted to extend beyond the boundary defined by the regions, whereas an active actor is not.
  • "Is Actor Active?" (usually define) - A switch indicating whether the actor is passive or active. An active actor releases molecules into the environment (i.e., a transmitter). A passive actor observes molecules in the environment (i.e., a receiver). Default is false.
  • "Start Time" (usually define) - A number indicating the start time (in seconds) of the actor's behavior. The global simulation start time is 0 and the end time is set by "Final Simulation Time" in the "Simulation Control Object", so "Start Time" should be between these two values. Default value is 0. Actors that act at the same instant could do so in a random order. In order to impose a specific order, a small offset to an actor's start time can be used. This can also be done in consideration of the microscopic time step.
  • "Is There Max Number of Actions?" (usually define) - A switch indicating whether the actor has a preset maximum number of actions. One action is the start of a symbol interval (i.e., modulated data symbol) for an active actor or an observation of molecules by a passive actor. Default value is false.
  • "Max Number of Actions" (optional) - A positive integer number of actions for the actor to perform. Only needed if "Is There Max Number of Actions?" is true. The actor may perform fewer actions if the "Final Simulation Time" is reached first. Default value is 1.
  • "Is Actor Independent?" (usually define) - Switch to indicate whether the actor is independent. The actual value is ignored and will be accounted for in a future release. Default value is true, since currently all actors are independent.
  • "Action Interval" (usually define) - A number indicating the time (in seconds) between actions performed by the actor. Default value is 1.
  • "Is Actor Activity Recorded?" (usually define) - Switch to indicate whether the actor's actions are recorded in the simulation output file. Active actor activity is its sequence of emitted symbols. Passive actor activity is the number of each type of molecule that is observed (and optionally the coordinates of those molecules). Default is true.
  • "Random Number of Molecules?" (optional) - A switch indicating whether the precise number of molecules released by the transmitter for a given symbol is random or deterministic. Only needed if the actor is active. Default is false. See table below for how this parameter controls the release of molecules.
  • "Random Molecule Release Times?" (optional) - A switch indicating whether the precise molecule release times within a symbol interval are random or deterministic. Only needed if the actor is active, and only used if "Random Number of Molecules?" is true. Default is false. See table below for how this parameter controls the release of molecules.
  • "Release Interval" (optional) - A non-negative number indicating the time (in seconds) that an active actor will release molecules for a given interval. Analogous to pulse width. The value can be larger than the "Action Interval", i.e., an active actor can be performing multiple actions simultaneously. Only needed if the actor is active. Default value is 0 (i.e., molecules are released instantaneously). See table below for how this parameter controls the release of molecules.
  • "Slot Interval" (optional) - A non-negative number indicating the period (in seconds) between molecule releases within a single "Release Interval". Only needed if the actor is active, and only used if "Random Number of Molecules?" is false. Default value is 0. See table below for how this parameter controls the release of molecules.
  • "Bits Random?" (optional) - A switch indicating whether the bit sequence, whose symbols are modulated by an active actor, is randomized. Only needed if the actor is active and the modulation scheme is not "Burst". Default value is true.
  • "Bit Sequence" (optional) - An array of binary values specifying the bits that are to be modulated by an active actor. Only needed if the actor is active, the modulation scheme is not "Burst", and and "Bits Random?" is false. The length of the sequence should be consistent with "Max Number of Actions" and "Modulation Bits", otherwise "Max Number of Actions" will be corrected. Default value for each element is 0.
  • "Probability of Bit 1" (optional) - A value between 0 and 1 that defines the probability that given bit in an active actor's data sequence will have value 1. Only needed if the actor is active, the modulation scheme is not "Burst", and "Bits Random?" is true. Every bit is determined independently. Default value is 0.5.
  • "Modulation Scheme" (optional) - A string defining the modulation scheme used by an active actor. Options are "CSK" (Concentration shift keying) and "Burst". For "CSK", the actor will release a number of molecules that is (on average) linearly proportional to the current data symbol. For "Burst", the actor will release (on average) a constant number of molecules (of possibly multiple types) in every action interval. Only needed if the actor is active. Default value is "CSK".
  • "Modulation Bits" (optional) - A positive integer number defining the number of bits in each symbol of an active actor's data sequence. Only needed if the actor is active and the modulation scheme is not "Burst". Default value is 1.
  • "Modulation Strength" (optional) - A positive number defining the strength of an active actor's molecule emissions. The precise use of this value (as either a rate or an absolute number of molecules) depends on how the actor's other transmission parameters are defined. Specifically, for "CSK" modulation, the strength is an (average) number of molecules per slot if "Random Molecule Release Times?" is false, and an expected generation rate (in molecules per second) if both "Random Number of Molecules?" and "Random Molecule Release Times?" is true, where the number or rate are scaled by the value of the current symbol value. The behavior for "Burst" modulation is similar, except that the symbol value is always 1 and multiple types of molecules can be released simultaneously. Only needed if the actor is active. Default value is 1.
  • "Is Molecule Type Released?" (optional) - An array of switches indicating what type(s) of molecule is (are) released by an active actor. Length of the array should be equal to the "Number of Molecule Types". If the array does not have the correct length, then the first element is set to true. Otherwise, the default value of each element is false. For "CSK" modulation, all true elements after the first are ignored. Only needed if the actor is active.
  • "Is Time Recorded with Activity?" (optional) - A switch indicating whether the simulation time of each action of a passive actor should be recorded with the rest of the action information. Only needed if the actor is passive. Default is false.
  • "Is Molecule Type Observed?" (optional) - An array of switches indicating what type(s) of molecule is (are) observed by a passive actor. Length of the array should be equal to the "Number of Molecule Types". Only needed if the actor is passive. Default value of each element is true.
  • "Is Molecule Position Observed?" (optional) - An array of switches indicating whether a passive actor should record the position of every molecule that it observes. Length of the array should be equal to the "Number of Molecule Types". Only needed if the actor is passive. Default value of each element is false. To generate a meaningful simulation video, at least one passive actor should be recording molecule locations. However, doing so generally increases the output file size considerably.

Table Listing How Release Parameters are Intepreted

"Random Number of Molecules?" "Random Molecule Release Times?" How "Modulation Strength" is Applied
false n/a # of molecules in each slot within release interval
true false Expected # of moelcules in each slot within release interval
true true Expected release rate (molecules per second) over entire release interval


Here is a sample object for an active actor that is defined by two regions:

{
    "Is Actor Location Defined by Regions?": true,
    "List of Regions Defining Location": ["A", "B"],
    "Is Actor Active?": true,
    "Start Time": 0,
    "Is There Max Number of Actions?": true,
    "Max Number of Actions": 20,
    "Is Actor Independent?": true,
    "Action Interval": 100e-3,
    "Is Actor Activity Recorded?": true,
    "Random Number of Molecules?": false,
    "Release Interval": 25e-3,
    "Slot Interval": 5e-3,
    "Bits Random?": true,
    "Probability of Bit 1": 0.5,
    "Modulation Scheme": "CSK",
    "Modulation Bits": 1,
    "Modulation Strength": 200,
    "Is Molecule Type Released?": [true, false]
}

Here is a sample object for a passive actor whose location is defined manually:

{
    "Is Actor Location Defined by Regions?": false,
    "Shape": "Sphere",
    "Outer Boundary": [0, 0, 10e-6],
    "Is Actor Active?": false,
    "Start Time": 1e-10,
    "Is There Max Number of Actions?": false,
    "Is Actor Independent?": true,
    "Action Interval": 1e-3,
    "Is Actor Activity Recorded?": true,
    "Is Time Recorded with Activity?": false,
    "Is Molecule Type Observed?": [true, false],
    "Is Molecule Position Observed?": [false, false]
}