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
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.
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
- -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
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.
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
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.
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.
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.
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.
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
- -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.
Used for inetgrity testing of
swarm. Similar to verify but compares the results to a pre-calculated ensemble.
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
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 a stable ensemble for stability tests.
Configuration Options:
- nsys : Number of systems
- nbod : Number of bodies Command-line Options:
- -O : Text output file
- -o : Binary output file
Generate an ensemble with 12000 systems consisting of 4 bodies each. Put two lines in generate.cfg:
Generate the ensamble using
swarm generate
swarm generate -c generate.cfg -o ensemble.bin
Convert text files to binary files and vice versa.
Convert text to binary
- -I : Text input file
- -o : Binary output file
Convert binary to text
- -i : Binary input file
- -O : Text output file
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
