Defining your custom DB outputter

1. In order to define your own DB output configuration you need to start the model in Repast Simphony's GUI mode. The .rs-configuration that is used to setup a new configuration needs to define the following line in user_path.xml for each agent class that shall be logged (see step 2.b):

   <agents path="bin" filter="\<package\>.\<ClassNameOfAgentClassToLog\>"/>
   

2. In the scenario tree under the appropriate context (SocialContext in most cases) first right-click on Data-Sets and choose Add Data-Set. Note that instances to output need to be included in this context. If the context is not visible in the scenario tree define it in context.xml (id needs to be the same as defined in the model):

     <context id="SocialContext">
       <projection id="SocialNetwork" type="network"/>
     </context>
   

   1. Enter a meaningful name for your data-set.
   2. stepAgentClassSelectSelect the agent-class you want to log, i.e. that has the access-method(s) whose return values you like to store in the DB. Click Next.
   3. Add as much mappings to the data-set as you like. In order to log simple method return values click on the Add button and choose Add Simple Mapping. Click Next.
   4. On the last screen, define the scheduling of your data-set logging an click Finish.
3. In the scenario tree under the same context right-click on Outputter and select DB-Outputter. Select the previously created data-set. See DB-Outputter manual for detailed information on how to configure the DB outputter. See the ParMa manual for "A Note on Parameter Management" with respect to the meaning of the run information table.
4. Even if the DB outputter is able to create a new table for the specified data-set it is recommended to create or at least adapt the table manually since it still is not able to optimize the table definition (e.g. using a data type that is sufficient for your data but minimum in storage size). Again, see the DB-Outputter manual for more information.
5. Store your new RS configuration (File > Save as) in a new folder (usually under ./config/rs with ending .rs).
6. Select the respective folder in your model run configuration.

Interplay of ParMa and Repast Simphony

See PaRma-Docs on how to configure RS in order to use ParMa with RS batch runs.

Inserting parameter rows into DB

As discussed in ParMa's introduction each parameter set is associated with an unique parameter-set-ID. Therefore, each uses parameter set should be inserted as a row in the DB's main parameter table. There are at least two ways to insert multiple rows for batch runs into the table:

Setting the number of milieu groups

Some settings need to be adapted in order to adapt the number and distribution of milieu groups:

1. Setting the correct milieu key map to GMilieuPa.MILIEUS:

   PmParameterManager.setParameter(GMilieuPa.MILIEUS, new MilieuKeysMap());
   

2. Adapting MySQL tables defined in GSqlPa.TBLNAME_MILIEU_GROUPS_NAMES and GSqlPa.TBLNAME_MILIEU_GROUPS

Dealing with model run configurations

Eclipse uses launch configurations to define classpath, main method to call, JVM parameters, etc. It is a good practice to store these launch configurations. Choose menu Run > Run Configurations... and select the configuration you want to store in the project folder > Tab Common > Save as > Shared File and choose the destination folder (usually ./config/launcher).

When creating a new model run configuration it is most appropriate to choose a launch configuration that RS automatically creates and adapt it:

1. Start an existing GUI configuration, adapt it to your needs (e.g. change data sets and outputters), and store it into a new .rs folder. You should consider some issues when you want to select agens classes or context builder classes for the configuration:
   1. user_path.xml: It is important to define the classes here. The path entry may be empty but must be specified path="". The file may not contain a "agents path="../bin"/" entry without filter!
   1. The libs-specification in user_path.xml should be relative to the rs-folder!
   2. A sample user_path.xml file:

      <model name="KUBUS_PopDyn" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://repast.org/scenario/user_path">
              <classpath>
                      <entry path="../../../lib" />
                      <entry path="../../../bin"/>
                      <entry path="bin" annotations="false" ></entry>
                      
                      <agents path="../../../bin" filter="agents.AbstractHousehold" />
                      <agents path="../../../bin" filter="contexts.MarketCellContext" />
                      <agents path="bin" filter="contexts.NeighbourhoodContext"/>
                      <agents path="../../../bin" filter="contexts.AreaContext"/>
              </classpath>
      </model>
      

2. Define the .rs folder to use in the tab Arguments > Program Arguments:
   1. Batch runs:

      -interactive -params "${workspace_loc:KUBUS_PopDyn}/batch/batch_params_set01.xml" 
      "${workspace_loc:KUBUS_PopDyn}/kubus_sh06.rs"
      

   2. GUI runs:

      "${workspace_loc:KUBUS_PopDyn}/kubus_sh06.rs"
      

Objects in Context

Be aware that (agent) object may be present in a context hierarchy on more than one level. This is especially true when agents are organised in market cell context, PLZ contexts and/or milieu contexts. Consequently, one and the same object may appear several times when calling:

rootContext.getAgentLayer(Agent.class)

Therefore, in order to obtain unique collections of agents, use the following statement:

for (Agent agent : this.getAgentLayer(Agent.class)) {
        if (!agents.contains(agent)) {
                agents.add(agent);
        }
}