Revised 2006-09-05 DMB

Return to the Index

# Directory and File Structure

This document contains a guide to the files present in Avida, and where they are located.

## Filenames

Source code files in Avida follow a standard naming convention. The C++ core, in general, maintains one class per header/source file pair. The file name should exactly match the class that it defines. All header files use `.h` and all source files use `.cc` as their respective file extensions.

When you compile a program in C++, it goes through a compilation phase and then a link phase. The compilation phase takes each source (`.cc`) file and compiles it independently into an object (`.o`) file. In the link phase, all of these compiled object files are linked together into a single executable (such as `avida`).

Since the bodies of the methods are only in the source files, they only need to be compiled once into a single object file. If you place a function body in the header file it will get compiled again each time another class includes that header. Since a header will often be included because only one or two methods from a class are required, this can increase compile time dramatically -- a function will be compiled as long as its body is included, even if the method is never directly called within the object file being created.

For example: The cOrganism object is declared in the file `cOrganism.h` and fully defined in `cOrganism.cc`. When this file is compiled, it creates the object file `cOrganism.o`. Both the cPopulation class (`cPopulation.cc`) and the cTestCPU class (`cTestCPU.cc`) use the cOrganism object. Since the majority of its methods are defined in `cOrganism.cc`, the compiler only needs to be compile these methods once. During the link phase the linker connects the references together.

Occasionally short functions are implemented with their bodies directly in the header file. When a function compiled in one object file is run from another, the linker basically points the caller to the location of that function. A few extra CPU cycles must be expended while the program jumps to the function. Many small function, especially one line access methods, can be made inline, which means it will be placed, as a whole, right inside of the function that calls it. If the function is short enough, it only takes up as much space as the call to it would have taken anyway, and hence does not increase the size of the executable.

## Directory Structure

The following sections provide a high level overview of the directory structure within the Avida source code distribution. Many directory sections contain partial listings of the files contained within them, however these list are not to be considered complete.

### Top Level Directory

All of the files for the current version of Avida reside in the directory labeled `trunk/` by default when checked out of Subversion. In addition to the subdirectories `documentation/`, `source/` and `support/` (all described below), this directory contains several key sources of information and automatic compilation files. The most important of these are described here.

`AUTHORS`
  This file contains information about the authorship of Avida.
`Avida.xcodeproj`
  This file (or directory on non-Mac OS platforms) contains the Xcode project information for development and building Avida within the Xcode IDE on Mac OS. This project file requires Xcode 2.1 or greater.
`BuildAvida.py`
  The main entry point for the new experimental SCONS python based build system.
`CHANGES`
  A listing of important changes to Avida that affect users of previous releases.
`COPYING`
`COPYING.gpl`
  These files contain copyright information.
`KNOWN_BUGS`
  A listing of known issues that may be pertinent to various users.
`README`
  A general guide on how to get started once you put the Avida files on your machine.
`build_avida`
  A one step build script for compiling Avida under Unix platforms that have CMake installed.
`test_avida`
  After Avida has been built, this script serves as an entry point for executing a series of consistency tests on the produced executable.

### Directory: `build/work/` (CMake)
Directory: `build/{Target Name}/work/` (Xcode)

After compilation, this directory will contain all of the configuration files necessary for Avida (explained in more detail under in their own documentation files). The key files and directories here are:

`analyze.cfg`
  The default file used to write analysis scripts.
`avida.cfg`
  This is the main configuration file that is used by default.
`environment.cfg`
  This file contains the default environment information.
`events.cfg`
  This file contains the default event list.
`inst_set.default`
  This is the main, heads-based instruction set that is used by default.
`organism.default`
  This file contains the default starting ancestor of length 100.
`data/`
  This is the name of the default output directory and is created by Avida if it does not exist. The name and location of this directory can be configured in `avida.cfg`.

### Directory: `source/`

This is a large sub-directory structure that contains all of the source code that makes up Avida. Each sub-directory here includes its own CMake and SCONS build information. The high level purpose of each sub-directory is:

`actions/`
  Contains various source files that define action classes that are usable as schedule events and analyze commands. Also contains the cActionLibrary responsible for instantiating objects based on cString names.
`analyze/`
  Contains classes responsible for performing and managing data from detailed analyses.
`classification/`
  Classes that define and manage classification of current and past properties of the population are stored here.
`cpu/`
  Files and classes used to implement all of the virtual hardware within the Avida software.
`drivers/`
  Classes and infrastructure used to orchestrate the execution of Avida.
`event/`
  Contains classes responsible for event scheduling and triggering.
`main/`
  Contains all of the core classes that define the world and the population within it.
`platform/`
  Contains platform specific software in various subdirectories, such as the high performance malloc library for POSIX platforms.
`targets/`
  Target (executable) specific source code. The source code of the NCurses viewer resides in the `avida-viewer/` subdirectory.
`tools/`
  Contains a number of generic tools classes, including custom data structures and robust string manipulation classes.

### Directory: `source/main/`

This sub-directory contains all of the core source code files for the software. For ease, there are two separate groups of more important components and less important components, each in alphabetical order. The syntax `name.??` refers to header/source file pairs, `name.h` and `name.cc`. The more important files are:

`cAvidaConfig.??`
  These files define the cAvidaConfig object that maintains the current configuration state of Avida. This class is initialized by the avida.cfg file and processed command line arguments and can be modified via various events during the run.
`cEnvironment.??`
  This file defines the cEnvironment object, which controls all of the environmental interactions in an Avida run. It makes use of reactions, resources, and tasks.
`Genome.??`
  The Genome object maintains of a sequence of objects of class cInstruction.
`cInstruction.??`
  The cInstruction class is very simple, maintaining a single instruction in Avida.
`cInstLibBase.h`
  The cInstLibBase class serves as a base class for objects that associate instructions with their corresponding functionality in the virtual hardware.
`cMutationRates.??`
  These files contain the cMutationRates class which maintain the probability of occurrence for each type of mutation.
`cOrganism.??`
  The cOrganism class represents a single organism, and contains the initial genome of that organism, its phenotypic information, its virtual hardware, etc.
`cPopulation.??`
  The cPopulation class manages the organisms that exist in an Avida population. It maintains a collection of cPopulationCell objects (either as A grid, or independent cells for mass action) and contains the scheduler, genebank, event manager, etc.
`cPopulationCell.??`
  A cPopulationCell is a single location in an Avida population. It can contain an organism, and has its own mutation rates (but not yet its own environment.)
`cStats.??`
  A cStats object keeps track of many different population-wide statistics.
`cWorld.??`
  The cWorld object contains all of the state information used by a particular run and can be used to access many globally important classes.

Below are various less important files that may still be useful to know about:

`cOrgInterface.h`
  The cOrgInterface class defines the interface used by organisms to interact back with the population or test CPU environment.
`cReaction.??`
  The cReaction class contains all of the information for what triggers a reaction, its restrictions, and the process that occurs.
`cReactionResult.??`
  The cReactionResult class contains all of the information about the results of a reaction after one occurs, such as the amount of resources consumed, what the merit change is, what tasks triggered it, etc.
`cResource.??`
  The cResource class contains information about a single resource, such as its inflow rate, outflow, name, etc.
`cResourceCount.??`
  The resource count keeps track of how much of each resource is present in the region being tracked.
`cTaskLib.??`
  This class contains all of the information associated with task evaluation.

### Directory: `source/analyze/`

The primary class in this directory is `cAnalyze`. This class processes `analyze.cfg` files to perform data analysis on run data. The additional classes in this directory support various types of analyses, along with provide the foundation for multithreaded execution. The `cAnalyzeJobQueue` object, instatiated by `cAnalyze`, orchestrates queuing and executing jobs on parallel worker objects.

### Directory: `source/cpu/`

This sub-directory contains the files used to define the virtual CPUs in Avida.

`cCodeLabel.??`
  The cCodeLabel class marks labels (series of no-operation instructions) in a genome. These are used when a label needs to be used as an instruction argument.
`cCPUMemory.??`
  The cCPUMemory class inherits from the Genome class, extending its functionality to facilitate insertions and deletions. It also associates flags with each instruction in the genome to mark if they have been executed, copied, mutated, etc.
`cCPUStack.??`
  The cCPUStack class is an integer-stack component in the virtual CPUs.
`cHardwareBase.??`
  The cHardwareBase class is an abstract base class that all other hardware types must be overloaded from. It has minimal built in functionality.
`cHardwareCPU.??`
  The cHardwareCPU class extends cHardwareBase into a proper virtual CPU, with registers, stacks, memory, IO Buffers, etc.
`cHardwareManager.??`
  The cHardwareManager manages the building of new hardware as well Test CPU creation.
`cHardwareSMT.??`
  This class represents the in process experimental implementation of next generation virtual hardware.
`cHardwareTransSMT.??`
  An intermediate step on the path to cHardwareSMT, this transitional hardware is used in a number of ongoing research projects.
`cHeadCPU.??`
  The cCPUHead class implements a head pointing to a position in the memory of a virtual CPU.
`cTestCPU.??`
  The cTestCPU class maintains a test environment to run organisms in that we don't want to be able to directly affect the real population.
`cTestUtil.??`
  The cTestUtil utility class is for test-related functions that require a test CPU, such as printing out a genome to a file with collected information.

### Directory: `source/tools/`

The tools sub-directory contains C++ source code that is used throughout Avida, but is not specific to the project.

`cDataEntry.??`
  Associates data names with functions for printing out data file with a user specified format.
`cDataFile.??`
  A class useful for handling output files with named columns.
`cDataFileManager.??`
  This class manages a collection of data files and handles the creation and output of user-designed data files at runtime.
`cMerit.??`
  Provides a very large integer number, dissectable in useful ways.
`cRandom.??`
  A powerful and portable random number generator, that can output numbers in a variety of formats.
`cString.??`
  A standard string object, but with lots of functionality.
`cStringList.??`
  A specialized class for collections of strings, with added functionality over a normal list.
`cStringUtil.??`
  Contains a bunch of static methods to manipulate and compare strings.
`AvidaTools.h`
  Some useful math functions such as Min, Max, and Log.

Templates are special classes that interact with another data-type that doesn't need to be specified until the programmer instantiates an object in the class. Its a hard concept to get used to, but allows for remarkably flexible programming, and makes very reusable code. The main drawback (other than brain-strain) is that templates must be entirely defined in header files since separate code is generated for each class the template interacts with.

`tArray.h`
  A fixed-length array template; array sizes may be adjusted manually when needed.
`tBuffer.h`
  A container that keeps only the last N entries, indexed with the most recent first.
`tDictionary.h`
  A container template that allows the user to search for a target object based on a keyword (of type cString).
`tHashTable.h`
  A mapping container that maps keys to values using a hashing function to provide fast lookup.
`tList.h`
  A reasonably powerful linked list and iterators. The list will keep track of the iterators and never allow them to have an illegal value.
`tManagedPointerArray.h`
  A derivative of tArray, a managed pointer array is ideal for storing arrays of large objects that may need to be resized. The backing storage mechanism simple resizes an array of pointers, preventing the unnecessary copying of large objects.
`tMatrix.h`
  A fixed size matrix template with arbitrary indexing.
`tSmartArray.h`
  A derivative of tArray that provides hidden capacity management. This type of array is ideal for arrays of small objects that may be resized often.
`tVector.h`
  A variable-length array object; array sizes will be automatically adjusted to accommodate any positions accessed in it.

### Directory: `support/config/`

This directory contains all of the originals of the files that are copied into the `work/` directory on the installation process for the user to modify. There is also a `misc/` sub-directory under here with additional, optional configuration files that you may want to look at to see other possible pre-configured settings.

Return to the Index