- Generated by
1.17.0
|
Orrery
A GPU-accelerated N-body gravitational simulator
|
A run of Orrery is decided entirely by a configuration file and the revision of this repository that reads it. This document specifies the file. ADR-0031 records why the format is defined here rather than borrowed.
A file is a sequence of lines. Each is one of:
A key may name its own section, as solver.softening = 0.05. That form works anywhere, including before any heading and inside a different section, and it does not change the current section. It is what --set on the command line uses.
Everything is case sensitive. Values run to the end of the line and are not quoted, so there is no escaping rule and none is needed.
All of these are errors, reported with the file name and the line number:
Nothing is skipped and nothing is guessed. A run whose softenning was silently dropped is not a run that failed; it is a run that produced a plausible answer to a question nobody asked.
| Type | Accepted |
|---|---|
| number | Decimal, with an optional sign and an optional exponent: 0.001, -2, 1.5e-3. Read in the classic locale whatever the machine is configured for |
| whole number | Digits, not negative: 4096 |
| boolean | true or false, and nothing else |
| text | The rest of the line |
Every setting may be left out, and what is left out keeps the default below. A file states what it changes.
| Setting | Type | Default | Meaning |
|---|---|---|---|
| timestep | number | none | The interval of simulated time one step covers. Must be positive. There is no default worth having: the right timestep is a property of the configuration, roughly the shortest orbital period in it divided by a few dozen |
| steps | whole number | 0 | How many steps to take. Must be at least one |
| seed | whole number | 0 | The seed the initial conditions are sampled from |
A run is a number of steps rather than an interval of time. A finishing time would have to round somewhere, and the rounding would decide whether a resumed run took the same number of steps as an uninterrupted one.
| Setting | Type | Default | Meaning |
|---|---|---|---|
| kind | text | plummer | One of plummer, uniform-sphere, kepler, disc-galaxy, galaxy-collision |
| count | whole number | 0 | Particles, for the two sampled models. At least two. Not used by kepler, which is two bodies by definition |
| total_mass | number | 1 | Shared equally among the particles of a sampled model |
| scale_radius | number | 0 | The Plummer scale radius. Zero means 3 pi / 16, the value that puts a unit-mass sphere into standard N-body units |
| radius | number | 1 | The radius of the uniform sphere |
| mass_fraction_cutoff | number | 0.999 | The fraction of a Plummer model's mass the sample is drawn from. The model is infinite in extent, and truncating at 0.999 bounds the sample at 38.7 scale radii |
| primary_mass | number | 1 | The Kepler configuration's first body |
| secondary_mass | number | 1 | Its second |
| semi_major_axis | number | 1 | Of the relative orbit |
| eccentricity | number | 0 | In [0, 1). One or more is an unbound encounter with no period |
| bulge_fraction | number | 0.2 | The share of a galaxy's mass held by its bulge rather than its disc. In [0, 1) |
| scale_length | number | 1 | The exponential scale length of a galaxy's disc |
| scale_height | number | 0.1 | Its exponential scale height |
| bulge_radius | number | 0.2 | The Plummer scale radius of its bulge |
| inclination | number | 0 | The tilt of the disc's spin axis away from the z axis, in radians. Pi is the same disc turning the other way |
| position_angle | number | 0 | The angle the tilted disc is then turned by about the z axis, in radians |
| mass_ratio | number | 0.5 | The second galaxy of a collision as a fraction of the first. In (0, 1] |
| secondary_inclination | number | 1 | The second galaxy's tilt, in radians |
| secondary_position_angle | number | 0 | And its position angle |
| separation | number | 20 | The initial separation of the two galaxies along x |
| impact_parameter | number | 2 | The offset along y, which is what makes the encounter grazing rather than head on |
| approach_speed | number | 0.8 | The relative speed as a multiple of the escape speed at that separation. Below one the pair is bound and merges, at one the orbit is parabolic, above one they separate for ever |
A setting the chosen kind does not use is ignored, so one file may describe several configurations and select between them.
For both galaxy configurations, count and total_mass mean what they mean for the two spheres: the particles the run has and the mass they share. A collision divides both between its two galaxies in proportion to mass_ratio, so that every particle in the pair carries the same mass whatever the ratio is, and scales the smaller galaxy's three lengths by the square root of the ratio so that both have the same mean surface density.
A galaxy also reads solver.softening, which is the one place in this format where a setting crosses between sections. A disc is built at the speeds the forces it will feel can support, and those depend on the softening, so a galaxy assembled without it would start out of balance with the run about to be taken. include/orrery/initial_conditions/disc_galaxy.hpp sets out what the model does and does not claim to be.
| Setting | Type | Default | Meaning |
|---|---|---|---|
| kind | text | barnes-hut | One of direct, barnes-hut, sycl-direct, sycl-tree |
| softening | number | 0 | The Plummer softening length. Zero is exact point masses, which is what the analytic comparisons need |
| opening_angle | number | 0.5 | Barnes-Hut only, in [0, 1]. Above one a cell can be accepted while the particle being accelerated is inside it |
| leaf_capacity | whole number | 32 | The most particles a tree cell may hold and remain a leaf |
| quadrupole | boolean | false | Whether to carry the second moment of each cell. An accuracy option rather than an improvement (ADR-0024) |
| executor | text | work-stealing | One of serial, static, work-stealing. A run should use the default; the others exist so a measurement can reproduce a published figure |
| threads | whole number | 0 | Workers. Zero means one per core |
| allow_cpu_fallback | boolean | true | Whether a run may use the CPU when the GPU it asked for is absent |
The two sycl- values are accepted by the parser in every build, including one compiled without the GPU backend. A configuration file is a document and should mean the same thing whatever binary reads it; whether this machine can provide what it asks for is decided when the run is assembled.
| Setting | Type | Default | Meaning |
|---|---|---|---|
| kind | text | velocity-verlet | One of velocity-verlet, yoshida4, rk4 |
Velocity Verlet is the default on ADR-0011's argument. RK4 is here as the counterexample: of the same order as Yoshida and costing a third more per step, its energy error grows without bound where the symplectic pair stay inside an envelope.
| Setting | Type | Default | Meaning |
|---|---|---|---|
| trajectory_path | text | none | Where the binary trajectory goes. Empty writes none |
| trajectory_stride | whole number | 0 | Steps between frames |
| trajectory_velocities | boolean | false | Whether frames carry velocities as well as positions |
| diagnostics_path | text | none | Where the CSV diagnostics go |
| diagnostics_stride | whole number | 0 | Steps between measurements. These cost an N^2 pass, so this should be a few hundred rather than one |
| checkpoint_path | text | none | Where checkpoints go. One file, overwritten |
| checkpoint_stride | whole number | 0 | Steps between checkpoints |
A stride of zero writes at the two ends of the run and nowhere in between. The last step of a run is always written whatever the stride, so the state a run finished in is never absent from its own output.
Run it, and see what the settings resolve to without taking a step:
Override anything from the command line, using the same names:
1.17.0