-
Notifications
You must be signed in to change notification settings - Fork 20
Gams Project Configurator
Shortly before the release of version 1.0.0, a tool called the GAMS Project Configurator (GPC) was released into the master branch. The GPC is a dynamic code and project generation tool that helps developers generate new agent controllers and features like algorithms, platforms, transports, transport filters, and threads. In this wiki page, we will describe the major features of this powerful tool.
As with most other GAMS tools, help can be obtained by passing a -h or --help option or an invalid option to the script. For example, the following command will generate help information.
$GAMS_ROOT/scripts/projects/gpc.pl --helpGPC generates an Action Script into a project directory to aid the developer with compiling and simulating controllers and distributed algorithms. The Action Script comes in two flavors: Linux .sh and Windows .bat. The Linux Action Script can be ran from any terminal. The Windows .bat must be ran inside of a Visual Studio Developer Command Prompt in order to use the compile or compile-vrep option.
Examples (Linux and Windows, .sh and .bat, respectively)
action.sh|.bat help # get help and usage information
action.sh|.bat compile-vrep # compile the project to include V-REP support
action.sh|.bat compile # compile the project, potentially without V-REP support
action.sh|.bat compile-vrep vrep sim # compile the project for V-REP, launch vrep, and run the configured simThe GPC has dozens of options for generating, modifying, and running V-REP simulations. Configuring a simulation is one of the first target usages of GPC and the tool has many features to make interesting, realistic simulations.
By default, any project you create will have a simulation of one quadcopter in the center of a GPS region. For instance, the following actually generates the default one quadcopter simulation into the current directory:
$GAMS_ROOT/scripts/projects/gpc.plWe can make this simulation more interesting by scaling the number of agents and giving them random locations in the current region.
$GAMS_ROOT/scripts/projects/gpc.pl --agents 10 --randomizeTo run sims that you have configured, simply run the action script with vrep and sim
action.sh vrep sim # linux
action.bat vrep sim # windowsThe GPC help has good descriptions of these options, but the following list may help with configuring common simulation options (note the gpc.pl is located inside $GAMS_ROOT/scripts/projects):
gpc.pl --min-height 4 --unique # give all agents unique heights starting at 4m
gpc.pl --group group.allies # create a GAMS group called "group.allies" that contains all agents
gpc.pl --group group.allies --last 3 # create a GAMS group called "group.allies" that contains agent 0-3
gpc.pl --multicast "239.100.5.40:47000" # all agents should use a multicast transport for collaboration
gpc.pl --algorithm "debug" # all agents should use the "debug" algorithm
gpc.pl --distributed --invert --rotate # invert and rotate the formation, used in distributed formations
gpc.pl --platform "vrep-boat" # use a boat platform in V-REP instead of the vrep-quadTo generate a new algorithm that agents can use in a simulation or real-world test, the --new-algorithm or --na option should be passed with the name of the algorithm. GPC will generate a new algorithm into the src/algorithms directory and create a new custom controller in the src directory. In addition to the new named algorithm, the GPC will also generate an algorithm factory that allows the custom algorithm to be called remotely, at run-time, by users through karl or any interaction with a MADARA KnowledgeBase that has the same network transport configuration.
$GAMS_ROOT/scripts/projects/gpc.pl --new-algorithm my_algThe results of the call will be three files created:
src/algorithms/my_alg.h
src/algorithms/my_alg.cpp
src/controller.cppThe my_alg.h|cpp files should then be edited to include the logic necessary for the developer's distributed application. After changes have been made, the new controller can be compiled with either the compile or compile-vrep options.
When trying to optimize your GAMS projects, especially for simulations in VREP or Unreal, keep in mind the following performance issues:
1.) Launching many threads causes scheduling issues in the OS. The fewer threads, the better the system performance and scalability of simulations 2.) Input/Output, especially text-based printing and networking, is very expensive. If you can lower the GAMS and MADARA log levels without impacting your ability to debug, then your performance will be significantly better.
Threading overhead can become very significant as you scale GAMS simulations into hundreds of agents, especially on the same machine. There are two main sources for threads within the gpc.pl generated projects: controller threads and transport threads. Controller threads are created in two ways: 1) launching multiple custom controllers from the project's bin directory after compiling with action.sh and 2) launching new threads when you add a new thread to your project with gpc.pl -nt.
Transport threads are created by almost all MADARA network transports. You can select -nt from gams_controller or custom_controller to have no transport in your custom project. This means when you launch a sim, the agents will not communicate with each other between processes or hosts, so only use this if your agents are collocated in the same process. If you use the "--merge-controllers" option in your custom_controller, then you can merge many agent controllers into the same OS process, and the default settings for ControllerSettings that are passed into the Multicontroller indicate using shared memory transports for collocated, merged agent controllers. You can configure merging controllers in sims by updating the $mc variable in your sim/run.pl file that is generated by gpc.pl.
There are three main sources for IO latency in GAMS applications. You will find that the expense of IO operations, in terms of perceived performance of many agent simulations, will be from 1) text-based console logging, 2) logging to files, 3) checkpointing, and 4) networking.
To remove most logging, make sure that you set --gams-level and --madara-level to 1 or 2. These will only print ERRORS and WARNINGS, respectively. By default, new generations from gpc.pl may also have default debug algorithms and platforms that will print to the console so you can tell the GAMS control loop is operational. Set these to null by either passing in -A or -p to the custom controller or by changing the algorithm or platform to null with gpc.pl.
Logging to files is only done if you configure logging for this. Logging to files is more efficient and less blocking that console based logging, but if you don't have to log, it is best not to log. We recommend instead creating logging systems based on modifications to the knowledge base and then using checkpointing to save state.
Checkpointing can be enabled with many options from the custom controller interface. There are options to save on loop and send, and the ControllerSettings class includes distinctions for whether you want to save diffs or full context saves with each context being a separate file or all contained in one file. Checkpointing does affect performance, much less than logging, but disabling checkpointing (the default setting in your custom controller) is the optimal performance setting if you want to scale to hundreds of agents in a simulation.
Most MADARA options for networking are very fast, but there are also lots of qos settings that when enforced, slow down the control loops, especially on send. The absolute, fastest way to network between agents is to disable networking transports with the -nt option to the custom controller and then merge controllers of agents into one custom controller by using the -mc option with the number of agents you want the single process to control. This will cause a shared memory transport to be created that allows for applying on send and on receive filters, but most other QoS is ignored. The shared memory transport not only creates no threads, but it also does almost no copying between the knowledge bases. This reduces the performance penalty of using MADARA transports significantly.