Adding Parameters

Adding parameters in MABE is simple!

1. Add a static ParameterLink to your class to your .h file.
2. Add a call to Parameters::register_parameter to your .cpp file.
3. Use the parameter in your code.

Add a static ParameterLink to your class a .h file.

A static variable is a variable that exists outside of an instantiated object. When working with Parameters we used static variables because once we register a parameter we want it to persist and we want to be able to access it from anywhere in MABE.

The registerParameter() function (described below) returns a shared pointer to a ParametersLink (PL - a handle that lets us quickly access parameters). A static shared_ptr to a ParametersLink must be declared in a .h file (generally in the class where it will be used) to receive the PL created by a call to registerParameter(). The type of the ParameterLink must match the type of the parameter it links to. The declaration of a PL for an integer parameter called searchTime would look like:

static shared_ptr<ParameterLink<int>> searchTimePL;

The "PL" at the end of the variable name indicates that this variable is a parameter link. This is a convention, and while it is not required, it is strongly suggested that you follow it so that your code is more readable.

Add a call to Parameters::register_parameter to a .cpp file.

At the top of the associated .cpp file add the following.

shared_ptr<ParameterLink<TYPE>> [CLASS]::[PARAMETER_NAME]PL = Parameters::register_parameter("[CATEGORY]-[PARAMETER_NAME]", [DEFAULT_VALUE], "USAGE_MESSAGE");

for example, if you were wanted to add the integer parameter searchTime to SearchWorld:

shared_ptr<ParameterLink<int>> SearchWorld::searchTimePL = Parameters::register_parameter("WORLD_SEARCH-searchTime ", 30, "time organism has to locate target object");

Category names

In MABE all parameters names are made up of two parts, a category name, and a 'parameter name'. These two parts are separated by a "-". Within MABE the name of a parameter is actually the full name (category name + '-' +'parameter name'). The dash in the name is used when creating configuration files, where the category name is used to group parameters.

In addition to creating the parameter, the registerParameter() function also sets the parameters default value, the type (as derived from the default value) and a usage message to appear in config files.

String Parameters must have their default value preceded by '(string)' in order to be recognized as type string.

shared_ptr<ParameterLink<string>> SearchWorld::mapNamePL = Parameters::register_parameter("WORLD_SEARCH-mapName ", (string)"Arrakis", "name of map used to evaluate organism");

Working with Parameters in code

ParametersLinks (PLs) provide the interface to set parameter values and get parameter values.

At this point, you should be familiar with Mabe Parameter name spaces (if not check out: Parameters-Name-Space).

When a parameter is registered a PL for that Parameter is created. You can have different values for that parameter associated with different name spaces. In essence, there is a lookup table where different name space keys will return various values (while adhering to name space inheritance)

When you want to get a value from a PL you use:

auto val = searchTimePL->get(PT);

or

if (time > searchTimePL->get(PT)){ ...

When you want to set a value in a PL you use:

searchTimePL->set([VALUE],PT);

note that VALUE must match the type of the PL.

PT?
You should right now be wondering what PT is. PT stands for ParametersTable. Each name space (a string) has an associated Parameters Table. You can get the PT for a given name space with:

auto PT = Parameters::root->getTable([NAME_SPACE])

If the PT for the indicated NAME_SPACE already exists, the function will return a shared pointer to the PT. If not, MABE will create the name space and associated PT and return a shared pointer to the new PT.

Localizing Parameters

A lookup of a value from a PL is relatively fast, but many lookups can slow down execution. In some cases, it is a good idea to localize parameters - that is assign their value to a local variable. Some parameters can be localized in a constructor, others should be localized later.

• example 1:
  in test world, the user sets the number of outputs expected. This value sets the brain outputs and therefore can not change. This value can be localized in the constructor using a class member variable in TestWorld.
• example 2:
  a world parameter "attackCost" that might change from one generation to the next can not be localized in the world constructor, but this parameter could be localized in a world evaluate function so that it only needs to be looked up once per generation.
• example 3:
  in CGP brains, the values generated by each operator are capped between a user defined min and max. It is not uncommon for a CGP brain to perform hundreds of calculations per brain update. In CGP brains, these values are localized on each brain update. Now rather than needing to look up the value for each operation, we only look it up once per update, which results in a reasonable execution time.

  	auto magnitudeMax = magnitudeMaxPL->get(PT);
  	auto magnitudeMin = magnitudeMinPL->get(PT);