Skip to main content Skip to navigation

School of Engineering

AcCoRD Output

This page has instructions for reading and working with AcCoRD output files, including how to import them into MATLAB. These instructions assume that you have already generated the output files by running simulations. If not, then please refer to the Running AcCoRD page for details or the How to Use AcCoRD page for an overview. Once you output has been imported to MATLAB, you can refer to the AcCoRD Post-Processing page for creating plots and videos. Each AcCoRD simulation generates two output files. The files are named MY_OUTPUT_SEEDX.txt and MY_OUTPUT_SEEDX_summary.txt, where MY_OUTPUT is the "Output Filename" defined in the configuration file, and X is the seed value. We will refer to these two files as the main output file and the summary file, respectively. The summary file is written in JSON format. It provides some general information about the simulation, including the run time and the name of the configuration file that was used. Importantly, it also includes information on how to read the main output file. However, the recommended AcCoRD workflow does not include working directly with these files. MATLAB utilities are provided which scan the output into structures that are much more convenient to manipulate (see Import to MATLAB and then Post-Processing below). If you do not have access to MATLAB, or you need to do some debugging, then information is also provided below about reading the raw output files.

Importing to MATLAB

The recommended method to use AcCoRD output is by importing into MATLAB. AcCoRD comes with utility functions to read output files and facilitate post-processing (see more on processing below). These functions are all included in the "matlab" directory of the AcCoRD installation. To access these functions, this directory should be your current directory in MATLAB (or, alternatively, on your MATLAB path). Note: If the AcCoRD "matlab" directory is not your current directory, then you will also need to include the directory "JSONlab", which is inside the AcCoRD "matlab" directory, on your MATLAB path. The "JSONlab" directory is only needed when importing (and not post-processing). The primary import function, which you call directly from the MATLAB command line, is called accordImport.m. It takes three arguments:

  1. filename - The prefix of your AcCoRD output files (i.e., without the "_SEEDX.txt" or "_SEEDX_summary.txt" suffixes). This should include a path to the file.
  2. seedRange - An array listing the seed values associated with the files that you want to import. All files need the same prefix and should have been created using the same configuration file (otherwise unexpected behavior may occur).
  3. bWrite - A switch to write the imported data to a MATLAB "mat" file. If true, then the file filename_out.mat will be created in the "matlab" directory, where "filename" is the filename argument but without any path.

The accordImport function also has up to two output arguments:

  1. data - Structure containing the simulation summary and output content.
  2. config - Structure containing the configuration parameters defined in the configuration file, but only if the configuration file can be found. MATLAB will search for the file as specified in the "ConfigFile" string of the summary file (but not including the path). It will search relative to the current directory, and then a number of variations including the parent directory, grandparent directory, and a "config" directory that is either in the current directory of in the parent or grandparent directory. If the file cannot be found, then the "config" output is an empty array.

The "data" Structure

The fields of the "data" structure are as follows (including indexing information where applicable):

  • "numSeed" - The number of seed values that were aggregated.
  • "seed" - The array of seed values that were aggregated.
  • "configName" - The name of the original configuration file (not including the path)
  • "startTime" - The computer time at the start of execution (but after loading the configuration file and initializing the system parameters) of the first seed value.
  • "endTime" - The computer time at the end of the simulation (but before memory cleanup) of the first seed value.
  • "numRepeatSingle" - The number of realizations simulated by the first seed.
  • "numRepeat" - The number total number of realizations by all seeds, assuming that the same number of realizations was simulated by each seed.
  • "numActive" - The number of active actors whose behavior is recorded in the main output files.
  • "activeID" - Array containing the numeric IDs of the active actors. Numbering of IDs starts at 0 and follows the order of all actors (active and passive) in the configuration file.
  • "activeMaxBits" - Array containing, for each active actor, the length of the longest bit sequence among all realizations simulated by the first seed.
  • "activeBits" - Cell array of matrices containing the transmitted bits of each active actor in every realization. Indexing has format activeBits{i}(j,k) for the kth observation by the ith active actor in the jth realization.
  • "numPassiveRecord" - The number of passive actors whose behavior is recorded in the main output files.
  • "passiveRecordID" - Array containing the numeric IDs of the passive actors. Numbering of IDs starts at 0 and follows the order of all actors (active and passive) in the configuration file.
  • "passiveRecordBTime" - Array of switches indicating whether the times of the passive actor's observations were recorded.
  • "passiveRecordMaxCountLength" - Array containing, for each passive actor, the largest number of observations made by actor in any single realization simulated by the first seed.
  • "passiveRecordNumMolType" - Array of the number of types of molecules observed by each passive actor.
  • "passiveRecordMolID" - Cell array of arrays, each of length "passiveRecordNumMolType", indicating the numeric IDs of the types of molecules that were observed by each passive actor. Numbering of IDs starts at zero. Indexing has format passiveRecordMolID{i}(j) for the jth type of molecule observed by the ith passive actor.
  • "passiveRecordBPos" - Cell array of arrays of switches, each of length "passiveRecordNumMolType", indicating whether the passive actor recorded the positions of the molecules that were observed. Indexing has format passiveRecordBPos{i}(j) for the jth type of molecule observed by the ith passive actor.
  • "passiveRecordTime" - Cell array of matrices, each of size "numRepeat" by "passiveRecordMaxCountLength", storing the observation times by each passive actor in every realization. Only written to if "passiveRecordBTime" is true. Indexing has format passiveRecordTime{i}(j,k) for the kth type of molecule observed by the ith passive actor in the jth realization.
  • "passiveRecordCount" - Cell array of 3D arrays, each of size "numRepeat" by "passiveRecordNumMolType" by "passiveRecordMaxCountLength", storing the number of molecules of each type observed by each passive actor in every realization. Indexing has format passiveRecordCount{i}(j,k,m) for the mth observation of the kth type of molecule observed by the ith passive actor in the jth realization.
  • "passiveRecordPos" - Cell array of cell arrays, each of length "passiveRecordNumMolType", of 2D cell arrays, each of size "numRepeat" by "passiveRecordMaxCountLength", of N by 3 matrices indicating the coordinates of every molecule observed by each passive actor in every realization. Only written to for elements of "passiveRecordBPos" that are true. Indexing has format passiveRecordPos{i}{j}{k,m}(n,p) for the pth coordinate of the nth molecule of the jth type observed by the ith passive actor in the mth observation of the kth realization.

The "config" Structure

The fields of the "config" structure are mostly analogous to those in the corresponding configuration file. The fields match as follows (refer to the AcCoRD Configuration Parameters page for more details about the configuration parameters):

  • "outputFilename" - “Output Filename”
  • "numRepeatPerSeed" - “Number of Repeats”
  • "dt" - “Global Microscopic Time Step”
  • "tFinal" - “Final Simulation Time”
  • "numMolTypes" - “Number of Molecule Types”
  • "diffusionCoeff" - matrix where every row contains the diffusion coefficients for that region. Unless the region defined “Local Diffusion Coefficients”, the global “Diffusion Coefficients” are used.
  • "numChemRxn" - length of the “Chemical Reaction Specification” array
  • "chemRxn" - Array of structures corresponding to “Chemical Reaction Specification”. The fields of each structure may include (as appropriate):
    • "rate" - “Reaction Rate”
    • "label" - “Label”
    • "bReversible" - “Is Reaction Reversible?”
    • "revLabel" - “Reverse Reaction Label”
    • "bSurface" - “Surface Reaction?”
    • "surfRxnType" - “Surface Reaction Type”
    • "surfTransProb" - “Surface Transition Probability”
    • "diffusion" - “Surface Reaction Diffusion Coefficient”
    • "bEverywhere" - “Default Everywhere?”
    • "numExceptions" - length of the “Exception Regions” array
    • "exceptionRegions" - “Exception Regions”
    • "reactants" - “Reactants”
    • "products" - “Products”
    • "bProdReleased" - “Products Released?”
    • "releaseType" - “Release Placement Type”
  • "subBaseSize" - “Subvolume Base Size”
  • "numRegion" - length of the “Region Specification” array
  • "region" - Array of structures corresponding to “Region Specification”. The fields of each structure may include (as appropriate):
    • "label" - “Label”
    • "parent" - “Parent label”
    • "shape" - “Shape”
    • "type" - “Type”
    • "surfaceType" - “Surface Type”
    • "bMicro" - “Is Region Microscopic?”
    • "numSubDim" - “Number of Subvolumes Per Dimension”
    • "subvolSizeInt" - “Integer Subvolume Size”
    • "radius" - “Radius”
    • "anchorCoor" - “Anchor Coordinate”
  • "numActor" - length of the “Actor Specification” array
  • "numActive" - number of actors in the “Actor Specification” array that are active
  • "numPassive" - number of actors in the “Actor Specification” array that are passive
  • "actor" - Array of structures corresponding to “Actor Specification”, where only the parameters that are common to both active and passive actors are stored. The fields of each structure may include (as appropriate):
    • "bDefinedByRegions" - “Is Actor Location Defined by Regions?”
    • "numRegion" - length of the “List of Regions Defining Location” array
    • "regionList" - “List of Regions Defining Location”
    • "shape" - “Shape”
    • "boundary" - “Outer Boundary”
    • "bActive" - “Is Actor Active?”
    • "startTime" - “Start Time”
    • "bMaxActions" - “Is There Max Number of Actions?”
    • "maxActions" - “Max Number of Actions”
    • "bIndependent" - “Is Actor Independent?”
    • "actionInterval" - “Action Interval”
    • "bRecord" - “Is Actor Activity Recorded?”
    • "activeID" - if actor is active, this number indicates the index of the corresponding active actor parameters in the "activeActor" array of structures
    • "passiveID" - if actor is active, this number indicates the index of the corresponding active actor parameters in the "passiveActor" array of structures
  • "activeActor" - Array of structures corresponding to the active actors in “Actor Specification”. The fields of each structure may include (as appropriate):
    • "actorID" - index of the corresponding common actor parameters in the "actor" array of structures.
    • "bRandNumMolecules" - “Random Number of Molecules?”
    • "bRandReleaseTimes" - “Random Molecule Release Times?”
    • "releaseInterval" - “Release Interval”
    • "slotInterval" - “Slot Interval”
    • "bBitsRandom" - “Bits Random?”
    • "probBitOne" - “Probability of Bit 1”
    • "bitSequence" - “Bit Sequence”
    • "numBits" - length of the “Bit Sequence” array
    • "modScheme" - “Modulation Scheme”
    • "numModBits" - “Modulation Bits”
    • "modStrength" - “Modulation Strength”
    • "bReleaseType" - “Is Molecule Type Released?”
  • "passiveActor" - Array of structures corresponding to the passive actors in “Actor Specification”. The fields of each structure include:
    • "actorID" - index of the corresponding common actor parameters in the "actor" array of structures.
    • "bRecordTime" - “Is Time Recorded with Activity?”
    • "bRecordMolCount" - “Is Molecule Type Observed?”
    • "bRecordMolPosition" - “Is Molecule Position Observed?”

Note: It is generally expected that necessary configuration parameters are defined by the configuration file (i.e., any case that results in a warning about a missing parameter at simulation run time would result in an error here).

Reading AcCoRD Output Files

AcCoRD output files are technically readable but are not intended for primary post-processing. The summary file contains two JSON objects and is written so that the original configuration file is not needed to import the actor behavior to MATLAB (however, the original configuration file is needed to import all of the simulation parameters). The first object has the following fields:

  • "ConfigFile" - The name of the configuration file used to define the simulation environment (including the path if it was provided).
  • "SEED" - The seed value used to initialize the random number generator. Does not necessarily match the one in the configuration file since it can be defined at run time.
  • "NumRepeat" - The number of independent realizations.
  • "StartTime" - The computer time at the start of execution (but after loading the configuration file and initializing the system parameters).

The second object in the AcCoRD summary file has the following fields:

  • "NumberActiveRecord" - The number of active actors whose behavior is recorded in the main output file.
  • "ActiveInfo" - An array of objects, one for each active actor whose behavior was recorded. Each of these objects has the following fields:
    • "ID" - The numeric ID of the actor. Numbering starts at 0 and follows the order of all actors (active and passive) in the configuration file.
    • "MaxBitLength" - The length of the longest actor bit sequence, among all realizations.
  • "NumberPassiveRecord" - The number of passive actors whose behavior is recorded in the main output file.
  • "RecordInfo" - An array of objects, one for each passive actor whose behavior was recorded. Each of these objects has the following fields:
    • "ID" - The numeric ID of the actor. Numbering starts at 0 and follows the order of all actors (active and passive) in the configuration file.
    • "bRecordTime" - Switch indicating whether the times of this actor's observations were recorded.
    • "MaxCountLength" - The largest number of observations made by the passive actor in any single realization.
    • "NumMolTypeObs" - The number of types of molecules that the actor observed.
    • "MolObsID" - The numeric IDs of the types of molecules that were observed. Numbering starts at zero.
    • "bRecordPos" - Array of switches of length "NumMolTypeObs". Indicates whether the actor recorded the positions of the molecules that were observed.
  • "EndTime" - The computer time at the end of the simulation (but before memory cleanup).
  • "RunTime" - The total run time of the main simulation loop (excludes initialization and cleanup, so should scale linearly with the number of realizations).

The main output file is not written in JSON. Instead, a simple ASCII format is used for fast importing into MATLAB. The structure is as follows:

Realization #: (repeats for every realization)
    ActiveActor #: (repeats for every active actor with recorded data)
                   (numbering follows the actor IDs)
        [Actor bit sequence]
    PassiveActor #: (repeats for every passive actor with recorded data)
                    (numbering follows the actor IDs)
        MolID #: (repeats for every type of molecule observed by actor)
            Count:
                [Number of molecules in each observation]
            Position: (Only if bRecordPos is true for this molecule type)
                [Array of arrays of 3D molecule locations for every observed
                molecule. Each molecule location is defined within (), and
                all molecules for a single observation are also within ()]

The Next Step

Once your AcCoRD output has been imported to MATLAB, you can use the MATLAB utilities for post-processing.