This is a start at documenting the usage of the command-line fo program, which can ingest a file full of astrometry in 80-column MPC format, PSV ADES, XML ADES, or a mix of any of these and output orbital elements and ephemerides. You can click here for information about building fo (and other tools) from source code on Linux or OS/X or *BSD.
fo is, among other things, the basic engine behind the on-line NEOCP page. Every fifteen minutes, the server behind projectpluto.com checks for NEOCP updates. Once an hour, it runs fo to recompute orbital elements and ephemerides for all NEOCP objects, and updates their pseudo-MPECs accordingly.
People running 'fo' on non-Windows platforms download the source code and compile it. This is not something your average Windows user wants to have to do. It can, of course, be done; Daniel Parrott has kindly provided a nice guide to how to build Find_Orb for Windows using Microsoft Visual Studio. There's also a not-really-documented way to cross-compile for Windows from Linux, using the Mingw-w64 compiler. But most people will click here for a pre-built fo64 for 64-bit Windows, or instead click here for a pre-built fo32 for 32-bit Windows.
Before downloading either version, you should first have the interactive console vesion of Find_Orb set up and running to your satisfaction. The command-line Windows Find_Orb will piggyback off that, borrowing settings and files for things such as the JPL ephemerides, default ephemeris settings, and so forth. If you've set up console Find_Orb to generate ephemerides that contain radial velocities, for example, then (at least by default) the command-line Find_Orb will use that setting as well.
Windows users would then download one or both of the above two executables (each is about 700 KBytes) and save it/them in the folder containing console Find_Orbs. You're then ready to run fo32.exe or fo64.exe from a command line. You can just run
fo64 (filename)
(fo32 on 32-bit systems) where filename
contains the astrometry in question. Henceforth, I'll refer to
all three flavors -- fo32 for 32-bit Windows, fo64
for 64-bit Windows, and fo for Linux, OS/X, and *BSD --
as fo. The actual running of the software is basically
identical on all systems, much as the way in which interactive
Find_Orb is basically identical.
I ran fo on a file containing astrometry for four new objects from NEOCP. On the screen, I got an "executive summary", giving me a little information about each object :
Processing 4 objects 1: C15C4C2; a=1.099, q=0.974, e=0.113, i=9 H=26.5 MOID 0.031 23 obs; 2019 Oct. 8-10 2: P10SBuQ; a=2.064, q=1.136, e=0.449, i=3 H=24.3 MOID 0.138 8 obs; 2019 Oct. 7-9 (41.2 hr) 3: P10SBxr; a=1.821, q=1.678, e=0.079, i=22 H=20.5 8 obs; 2019 Oct. 7-9 (43.0 hr) 4: P10SyjK; a=2.389, q=1.590, e=0.335, i=1 H=20.6 14 obs; 2019 Sept. 25-Oct. 10
Meanwhile, the following files were made :
Ephemerides are a little trickier. Both plain text and JSON ephemerides are emitted. You can adjust the text output name with the -e switch.
As described above, the ephemerides will default to including whatever quantities you had in GUI Find_Orb. (The -E switch described below can override that.)
There is a twist to this : if you select 'computer friendly' output, then total.json will contain ephemerides for each object. So you _can_ actually get ephemerides for each object... though I realize that not everybody is a fan of the JSON format.
You can, if desired, tell fo to produce JSON elements and ephemerides in separate files for each object, and you can tell fo to produce ephemerides for multiple MPC codes.
It is possible to set the ephemeris start date/time, step size, and number of steps on the command line. For example,
fo (filename) (other options) "EPHEM_START=2019 Jan 13 10:00" EPHEM_STEPS=40 EPHEM_STEP_SIZE=1h
would cause the ephemerides to start at that time, and give you 40 entries with a one-hour spacing. The start date/time has the same wide degree of flexibility as other date inputs in Find_Orb.
The following command-line options are available. Most work in both interactive Find_Orb and with fo.
-c Combine all observations as if you only had one object.
-C (MPC code(s)) Reset MPC code(s) for which ephems are generated. Similarly, you can skip this and just use the code from the last ephemeris.
Usually, you'd just specify one MPC code, but you can specify a comma-separated series of MPC codes and get ephemerides for each. For example, -C 500,G96,C95 would result in three sets of ephemerides being generated, for (500) geocentric, (G96), Mt. Lemmon, and (C95) SATINO. This can result in a hefty speedup, because the actual orbit is only computed once; in most cases, the various ephems won't take very long.
Be warned that by default, the ephemerides will overwrite each other, and you'd only get the last one. If you want to have separate JSON ephems written for each code, use the %c specifier in the JSON_EPHEM_NAME or JSON_COMBINED_NAME lines. If you want separate text ephemeris files, then use the %c specifier with the -e switch. (If you don't change at least one of them to include %c, there is really no point in specifying multiple observatory codes with the -C switch.)
-D (filename) Reset the 'environment' (settings) file name.
-e (filename) Direct the ephemeris output to that filename. Note that, as with the JSON output, you can put %c in the filename and have it replaced with the MPC code, and/or %p and have it replaced with the packed designation.
-E (options) Reset quantities output to ephemerides. If you skip this, you'll just get whatever output options were set the last time you ran Find_Orb, so it may be more convenient just to run that program and generate an example of the sort of output you want. The quantities can be any combination of :
3 Alt/az output
4 Radial velocity
5 Apparent angular motion (total motion and PA)
6 Phase angle
8 Ground track (lat/lon/alt)
9 Apparent angular motion (separate RA/dec components)
10 Round to nearest step. If the ephem starts at 03:14:15.9
and the step size is one minute, the first output will
be for 03:14.
11 Phase angle bisector
12 Heliocentric ecliptic lat/lon
13 Topocentric ecliptic lat/lon
14 Visibility indicator (sun/moon/twilight).
15 Suppress unobservable ephemeris data (below horizon, sunlit)
16 Show ephemeris uncertainties
17 Computer-friendly output. Dates are in JD, RA/dec in decimal
degrees, etc. Distances are always in AU, instead of
switching to km for close objects. And so on.
18 Output MOIDs for eight planets. Helpful to show how the MOID
for a given planet changes with time.
19 Space velocity (i.e., total speed of the object relative to
the observer, not just the radial component given by 4)
20 Lunar elongation
21 _Don't_ show RA/dec
22 _Don't_ show distance between observer and target
23 _Don't_ show distance between object and sun
24 _Don't_ show elongation from the sun
25 Show sun's altitude
26 Show sun's azimuth
27 Show moon's altitude
28 Show moon's azimuth
29 Sky brightness, in magnitudes/arcsec^2
30 Position angle from object to the sun (PsAng)
31 Position angle of object's heliocentric velocity (PsAMV)
32 Angle between observer-to-object vector and the object's heliocentric
orbit plane (PlAng)
(30-32 are of interest to some comet researchers, and correspond
to the quantities PsAng, PsAMV, and PlAng in JPL's Horizons system.)
33 Galactic lat/lon
34 Galactic 'confusion' (0=not many background galactic stars, 100=total confusion)
35 SNR
36 Exposure length
37 Explanations at the end of the text ephems (doesn't affect JSON)
38 Constellation
You can combine these in a reasonably straightforward way; for example, to tell fo to show alt/az, phase angle, heliocentric and topocentric ecliptic coordinates, and the visibility indicator (quantities 3, 6, 12-14), you would use -E 3,6,12-14.
-F (filename) : Output observations to (filename) in the punch-card (80-column) format, with observed positions and magnitudes replaced with computed positions and magnitudes. The result, if fed back into Find_Orb, would have nearly zero residuals in magnitude and position (not quite zero due to the limited precision of the 80-column format). The magnitudes will all be in V.
I don't think most people will have much use for this. I've used it for testing : if feeding its output back into Find_Orb did not yield near-zero residuals, it would mean I had a bug to fix.
-h : Display planet-centric orbits if the object is, at the time of the epoch, within a planet's "sphere of influence". Thus, artsats would be shown with geocentric orbits, irregular satellites of Saturn with Saturnicentric orbits, and so on. By default, you'll always get heliocentric orbits.
-N (filter) : Specify the (unpacked) names of the object(s) to be processed. (By default, all objects will be processed.) For example, -N 2022 VT1 would cause the object 2022 VT1 to be processed.
Additional objects can be specified in a comma-separated list, such as C/2004 V6,P/2010 PB57,C/2020 V2. * and ? can be used as wild-card characters; for example, 2018 B* would cause all objects from the last half of January 2018 to be processed; 2018 B*,2019 C* would add objects from the first half of February 2019.
Also, see the -P (filter) option to filter on the packed designation.
-o (obj_name) : Specify an object name. If that object exists in mpcorb.sof or orbits.sof, fo will extract the elements for it, and you'll see a 'dummy' observation (Find_Orb is oriented toward finding orbits from observations, so it generates a synthetic one at epoch.) If the -v option is used, fo will make use of the state vector extracted from that.
-P (filter) : Specify the packed designations of the object(s) to be processed. (By default, all objects will be processed.) For example, -N C1AUGE1 would cause the object C1AUGE1 to be processed.
Additional objects can be specified in a comma-separated list, such as C1AUGE1,P21A4e6,A10TKo1. * and ? can be used as wild-card characters; for example, A10* would cause all ATLAS objects to be processed; A10*,P21* would add all (F52) PANSTARRS objects.
Also, see the -N (filter) option to filter on the full (unpacked) name.
-v(state vect) : Specify a state vector. The -o option must also be used, to specify the object name. An example of how to specify the state vector :
fo -oMade-up -v2020jan13,1.2,2.3,3.4,-.005,.002,.001,H=17,eq
In this instance, the 'made up' object has a state vector with an epoch of 2020 Jan 13. (A JD or MJD could have been used instead; as is usual in fo, time entry is flexible.) The state vector is given as six values, three positions in AU and three velocities in AU/day. The H value is specified as 17, and the vectors are in the J2000 equatorial frame (default would have been ecliptic frame vectors.)
In addition to the eq and H= keywords, one can use km and s to switch from units of AU and days. For example,
fo -oMade-up -v2020jan13,1.49e+8,1e+6,-2e+6,0,29.8,0,km,s
would create an object one AU from the sun at epoch, moving in a very earthlike orbit.
-r(seconds1,seconds2) : Set a 'soft' and 'hard' limit for the CPU time fo will be allowed to consume. This is useful in ensuring that hung processes are terminated. If you use, for example, -r60,65, then after fo has consumed 60 seconds of CPU time, it will be sent a "terminate" signal, which will usually cause it to close. At 65 seconds, it will be sent a "kill" signal and will be terminated even if it's completely hung up.
-R(date1,date2) : Set a range of dates within which observations will be loaded. -R1960.5,2021, for example, would allow any observation from mid-1960 to 2021 to be read, ignoring any outside that range. Other date formats are acceptable; for example, -R1960jul1,MJD59215 would be equivalent. For spaces, you have to use quote marks, such as "-R 1960 Jul 1, JD 2459215.5".
-tE(date) : Specify the epoch for orbital elements. For example, -te "2025 apr 17" (equivalently, -tEjd2460782.5 or -tE mjd60782) would cause all orbital elements to have that epoch.
JSON output: By default, JSON files for elements, ephemerides, a 'short' elements file, and and "combined" file with all the data merged together will be written out as described above. The elements file will contain both elements, observations, and residuals. It's generally a good idea to be able to see the detailed assumptions behind the elements : what observations were used, their residuals, and so on. But such files can get to be huge, and for some purposes, you may prefer to use the 'short' elements, which omit the observations and residuals.
If you prefer, you can add lines such as the following to environ.dat to put JSON files into specified places :
JSON_EPHEM_NAME=~/json/eph%p_%c.json JSON_ELEMENTS_NAME=~/json/ele%p.json JSON_SHORT_ELEMENTS=~/json/short%p.json JSON_COMBINED_NAME=~/json/com%p_%c.json
or, in Microsoft™ Windows,
WIN_JSON_EPHEM_NAME=c:/json/eph%p_%c.json WIN_JSON_ELEMENTS_NAME=c:/json/ele%p.json WIN_JSON_SHORT_ELEMENTS=c:/json/short%p.json WIN_JSON_COMBINED_NAME=c:/json/com%p_%c.json
In the above, '%p' will be replaced by the packed or temporary designation; '%c' will be replaced by the observatory code for the ephemeris. (The elements don't depend on the ephemerides, of course, and use of '%c' in JSON_ELEMENTS_NAME won't work). You don't have to include a '%p' or '%c', but if you don't, the JSON files will always be written to the same name. If a file contains multiple objects, you'll only have JSON files for the last object.
The '%p' and '%c' can go anywhere in the file names. For example,
JSON_EPHEM_NAME=~/json/%p/eph.json JSON_ELEMENTS_NAME=~/json/%p/ele.json JSON_COMBINED_NAME=~/json/%p/com.json
would make a directory for each object, with each directory containing an eph.json, ele.json, and com.json file. (All assuming you use the options described above to make ephemerides for each object. Leave that out, and all you'll get will be the element files.)
Note that the %p and %c trick also works with the -e switch to specify the filename(s) for text ephemerides.
If you look in the file environ.dat (on non-MS Windows machines, ~/.find_orb/environ.dat), you will see that it lists, in plain text, a lot of the settings used by Find_Orb : things such as the JPL ephemeris file to use, element references, and so on. They are reasonably well documented.
When Find_Orb starts for the very first time, this file doesn't actually exist, and Find_Orb will get those settings from environ.def (similarly found in the ~/.find_orb directory on non-Microsoft systems). If, at some point, you want to return to default settings, just delete environ.dat, and Find_Orb will go back to use of environ.def. (This is also useful if you just want to reset one particular setting; take a look at environ.def, and you'll know what the default values are for that setting.)
If you upgrade Find_Orb, you'll see that you have a new environ.def file, possibly with new comments in it that aren't present in your environ.dat file. If you find yourself looking at the latter and seeing undocumented settings, you should look at environ.def; it ought to tell you what you're looking at.
You can use this to specify multiple environ.dat-type files for use with fo (doesn't work with interactive Find_Orb yet). To do this, use the -D (filename) option described above. fo will skip environ.dat in that case, loading whatever files you specify instead. In case of conflict, later files will override previous ones.
I can be reached at pôç.ötulpťcéjôřp@otúlm. If you're a human instead of a spambot, you can probably figure out how to remove the diacritical marks...