Swarm executable is a command line user interface to Swarm-NG package.

Swarm executable can be used to accomplish different tasks:

Integrate an ensemble from a text input file
Examine log output files
Launch and test integrators
Generate stable ensembles
Convert binary files to text files

Command-line interface

Usage:
        swarm [options] COMMAND [PARAMETER VALUE VALUE ...]

Possible commands are: 
        integrate :  Integrate a [loaded|generated] ensemble
        benchmark :  Compare outputs for different methods of integrations
        verify    :  Verify an integrator against a reference integrator
        query     :  Query data from a log file
        test      :  Test a configuration against input/output files
        generate  :  Generate a new ensemble and save it to output file
        convert   :  Read input file and write it to output file (converts to/from text)

Options:

General Options:
  -c [ --cfg ] arg      Integrator configuration file
  --defaults            Use default values for required configuration options
  -h [ --help ]         produce help message
  -p [ --plugins ]      list all of the plugins
  -v [ --verbose ] arg  Verbosity level (debug output) 
  -q [ --quiet ]        Suppress all the notifications (for CSV generation)

Integation Options:
  -d [ --destination_time ] arg Destination time to achieve
  -l [ --logarithmic ] arg      Produce times in logarithmic scale
  -n [ --interval ] arg         Energy test intervals
  -i [ --input ] arg            Input file
  -o [ --output ] arg           Output file
  -I [ --text_input ] arg       Text Input file
  -O [ --text_output ] arg      Text Output file

Benchmark Options:
  --range arg           Parameter value range param=v1,v2,v3

Query Options:
  -t [ --time ] arg     range of times to query
  -s [ --system ] arg   range of systems to query
  -b [ --body ] arg     range of bodies to query
  -k [ --keplerian ]    output in Keplerian coordinates
  --astrocentric        output coordinates in astrocentric frame
  --barycentric         output coordinates in barycentric frame
  --origin              output coordinates in origin frame [default w/ 
                        Cartesian]
  --jacobi              output coordinates in Jacobi frame [default w/ 
                        Keplerian]
  -f [ --logfile ] arg  the log file to query

Typical use of swarm requires a command followed by several options and parameters specific to the command. There are some options that are general to all commands, but most options are only valid with specific commands.

General Options

Following options are interpreted by swarm regardless of the command used.

–defaults : Use a default configuration for required parameters. The default can be overriden in the command line or by specifiying a configuration file. The default configuration is:
```
integrator=hermite
nsys=16
nbod=3
time_step=0.001
log_writer=null
```
-c [ –cfg ] <configuration file>: Specifies path to the file containing configuration for various parts of swarm framework. This configuration will be used to configure all modules of Swarm-NG library. Configuration file syntax is:
```
param 1 = value
param 2 = value
```
Note that parameter name can contain spaces, the space is considered when parsing the file. Although the configuration file is optional, it is highly recommended. Because most components of the library require configuration and if the configuration is not provided by user, a predefined configuration will be used.
-p [ –plugins ] : Used without a command. Writes the list of plugins that are linked to the Swarm-NG library. This option can be usefull when you are selecting an integrator.
-v [ –verbose ] <verbosity level>: Specify a positive number for verobsity level. The higher the number, the more informational and debug messages will appear in output. The normal levels vary between 1 to 4. To see all messages, provide a large number (e.g. 10).
-q [ –quiet ] : Synonomous to -v -1. Suppress all messages and execute without producing any output other than the CSV output. This option is useful when trying to use the output to generate spreadsheets.
-h [ –help ] : Displays the brief help message

integrate: General purpose integration

Reads an ensemble from a file (Generates one if no input file specified) and integrates it. Statistical information about time progress and energy conservation will be written to output in specified intervals. The resulting ensemble is saved to a file if an output file is specified.

Examples:

swarm integrate -c test.cfg

swarm integrate -c conf1.cfg -d 100 -i INPUT.bin -o OUTPUT.bin

swarm integrate -c conf2.cfg -d 100 -n 10 -I INPUT.txt -O OUTPUT.txt

-c [ –cfg ] <configuration file>: Path to a configuration file that contains setting about how the integration should be done. It is recommended that you put all the parameters in the configuration file. Most of command-line options can be specified in the configuration file.
-d [ –destination-time ] <destination time> : Specify the destination time that the systems in the ensemble are going to be synced to. This option has the same effect and overrides "destination time" parameter from configuration file.
-n [ –interval ] <interval> : Specify intervals for summary output. If no interval is specified, then the summary will be given only at the end of the integration. This option has the same effect and overrides "interval" parameter from configuration file.
-l [ –logarithmic ] <base> : If this option is specified the intervals are generated on the logarithmic scale. The <base> is used as the base for exponential growth of the interval.
-i [ –input ] <binary input file> : Specify the input file containing positions and velocities for an ensemble in Swarm binary format. This is meant to be used to read the binary output of Swarm. To make input data for swarm, please use the text input files. This option has the same effect and overrides "input" parameter from configuration file.
-I [ –text-input ] <text input file>:Specify the input file containing positions and velocities for an ensemble in Swarm text format. To know more about how to generate an input file refere to Text Formats . This option has the same effect and overrides "text input" parameter from configuration file.
-o [ –output ] <binary output file> : Specify the output file where the resulting ensemble will be saved in Swarm binary format. The binary output files were meant to be used as input to swarm executable and are not meant to be parsed by third-party applications. To examine ensemble, use textual output. This option has the same effect and overrides "output" parameter from configuration file.
-O [ –text-output ] <text output file>:Specify the output file where the resulting ensemble will be saved in Swarm text format. To know more about how to read an output file refere to Text Formats . This option has the same effect and overrides "text output" parameter from configuration file.

benchmark: Stress test and Stability test for integrators

Put integrators under stress test and compare the timing and stability of different integration scenarios.

Benchmark requires a parameter name to iterate over and values for the parameter. Values can be listed in the command line or can be specified using from, to, inc switches for looping over numerical values.

       Parameter name should be a valid configuration parameter. In the current version, any 
       parameter can be iterated over, however some parameters should not be iterated over
       this behavior might change in future versions. 

       Paramaters that are usually used for benchmark are:
       - nsys : Number of systems
       - nbod : Number of bodies
       - integrator: Integrator plugin used for integration
       - config : Integrate using different configuration
       - blocksize: Number of systems in a block. only a few numbers are allowed: e.g 16, 32, 64

Options

You have to define a range for benchmarking using –range switch. The parameter to range can be in one of these three forms

param=value1,value2,value3 \ parameter "param" will iterate over the list ("value1","value2","value3")
param=start..finish \ parameter "param" will iterate over numbers in the interval [start, finish] incrementing by 1.
param=start..inc..finish \ paramater "param" will iterate over numbers in the interval [start, finish] using the specified increment amount that comes in the middle.

Examples:

Performs a stress test for a specific integration scenario using generated systems

swarm benchmark -c conf.cfg --range nsys=4000,8000,16000,32000

Integrate an ensemble stored in text format in testcase.txt using three different integrators and compare the time and stability.

swarm benchmark -c base.cfg -I testcase.txt --range integrator=hermite,rkck_fixed

Compare 3 completely different integration scenarios stored in 3 different files using the same test data.

swarm benchmark -I testcase.txt config=case1.cfg,case2.cfg,case3.cfg

Strees test for different number of bodies ranging from 3 to 9.

swarm benchmark -c conf.cfg nbod=3..9

Strees test for different number of systems ranging from 3000 to 9000 by the increment of 1000.

swarm benchmark -c conf.cfg nsys=3000..1000..9000

It will run for number of systems equal to 3000, 4000, 5000, 6000, 7000, 8000, 9000.

verify: Verifying correctness

Integrate ensembles in different scenarios and compare the results to a reference implementation.

First, the ensemble is integrated using the base configuration. The resulting ensemble is then used as reference ensemble. Then the different scenarios are executed and after each integration scenario the result is compared to reference ensemble. Positions and velocitios of each body is compared to corresponding body in the reference ensemble. Time of the corresponding systems should be close enough. The difference between values can be tolerated up to certain user-controlled threshold.

To use different scenarios, you can use the same syntax as benchmark command. While you can iterate over any parameter, it is recommended to iterate only over integrators and configurations.

Configuration Options

These options should be specified in the base configuration:

pos_threshold : Tolerated error when comparing positions. Difference between magnitude of positions should be less than threshold for verification to pass.
vel_threshold : Tolerated error when comparing velocities. Difference between magnitude of velocities should be less than threshold for verification to pass.
time_threshold : Tolerated error when comparing times. Difference between time of systems should be less than threshold amount for verification to pass.

Examples:

     Provided that basecpu.cfg contains all the configurations for hermite, euler and verlet integrators
     and integrator is set to a CPU integrator, the following line verifies the correctness of
     hermite, euler and verlet integrators versus a CPU implementation using data from testcase.txt

swarm benchmark -c basecpu.cfg -I testcase.txt integrator=hermite,rkck_fixed

query: Examine log files, for more advanced querying refer to \ref swarm-query

-f [ –logfile ] <file name> Input binary log file
-s [ –system ] <range> Range of the systems that should appear in the query report
-b [ –body ] <range> Range of the bodies that should appear in the query report
-t [ –time ] <range> Time range that for the query report
-k [ –keplerian ]: If specified, enables the Keplerian output (default is Cartesian)
[ –astrocentric, –barycentric, –origin, –jacobi ]: Choice of coordinate frames.

test: Integration testing

Used for inetgrity testing of swarm. Similar to verify but compares the results to a pre-calculated ensemble.

Overview

Options and execution is similar to integrate command. After the integration, the output file is loaded and is compared to the result of integration. The test is passed if the difference in time, positions and velocities is less than the user-controllable thresholds. cf. Configuration Options

Examples:

First Step: On machine A, generate the output file using a specific integration scenario:

MachineA$ swarm integrate -c integ.cfg -I testinput.txt -O testoutput.txt

Second Step: Copy all files to machine B, build swarm and test the same integration scenario using:

MachineB$ swarm test -c integ.cfg -I testinput.txt -O testoutput.txt && echo "Test Passed!"

generate: Generate stable ensemble for tests

Generate a stable ensemble for stability tests.

Options

Configuration Options:

nsys : Number of systems
nbod : Number of bodies Command-line Options:
-O : Text output file
-o : Binary output file

Examples:

Generate an ensemble with 12000 systems consisting of 4 bodies each. Put two lines in generate.cfg:

nsys=12000
nbod=4

Generate the ensamble using swarm generate

swarm generate -c generate.cfg -o ensemble.bin

convert: Convert I/O formats

Convert text files to binary files and vice versa.

Options

Convert text to binary

-I : Text input file
-o : Binary output file

Convert binary to text

-i : Binary input file
-O : Text output file

Examples

Convert text file to binary

swarm convert -I my.txt -o my.bin

Convert binary file to text

swarm convert -i my.bin -O my.txt