Building Find_Orb (and some other tools) from source code on Linux, *BSD, or OS/X

(Details on building on Windows to follow.)

If you're at the Catalina Sky Survey, the original CSS-specific version of this page may be useful. If you aren't, it probably won't be.)

Most people reading this, I expect, will want to be able to run the interactive console version of Find_Orb and/or its non-interactive version, fo. Because of some interdependencies, you will end up also building other tools for artificial satellite indentification, identifying short asteroid arcs with known asteroids, integrating orbital elements from one epoch to another, and so on. I'll document those a little better at some point, but will focus here on Find_Orb and fo.

Doing this will require source code from several of my GitHub repositories. 'lunar' provides basic astronomical functions (coordinate conversions, time systems, etc.) 'jpl_eph' provides code to read JPL ephemerides. 'sat_code' has the functions for earth-orbiting satellites. 'miscell' has code to download NEOCP and other astrometry, convert some oddball astrometry formats to the 80-column MPC punched-card format (including radar data), and so on. 'find_orb' relies on most of these to make the programs you're actually interested in.

The procedure for building and installing any of these Git repositories is roughly similar, but there are some nuances.

First, be advised: to build the code, you'll need the 'ncurses-devel' package. (It's not needed to run the code, just to build it.) If you end up using my tools for grabbing astrometry from MPC (more on those later), you'll also need the 'libcurl-devel' package (cURL being the library used for accessing files on-line). Actually, I'd install libcURL anyway; it's possible that future Find_Orbs will use it to automatically update various files (the list of MPC stations, earth orientation parameters, etc.) Running

sudo yum install ncurses-devel
sudo yum install libcurl-devel

(or its apt-get or equivalent on other systems) will get you what you'll need.

Second, I suggest keeping the code for these tools in a convenient place, by doing something such as

mkdir ~/find_orb
cd ~/find_orb

Next, 'git clone' the code. For simplicity, I'd just grab all the code, including 'miscell' :

git clone https://github.com/Bill-Gray/lunar.git
git clone https://github.com/Bill-Gray/sat_code.git
git clone https://github.com/Bill-Gray/jpl_eph.git
git clone https://github.com/Bill-Gray/find_orb.git
git clone https://github.com/Bill-Gray/miscell.git
cd jpl_eph
make libjpl.a
make install
cd ../lunar
make
make integrat
make install

Note that you'll get some 'cannot create directory: File exists' and similar errors. These aren't actually a problem. I haven't figured out how to suppress the warnings yet.

The first 'make' for the lunar project builds a library of basic astronomical functions and some utilities based upon them, including 'astcheck'. 'make integrat' separately compiles and links the Integrat code.

As a test, you should be able to run

~/find_orb/lunar/jd

and get the current date/time in calendar and JD form, expressed in ten different calendrical systems, plus the current Delta-T and TD-UTC values.

For all projects, 'make install' puts relevant executables in ~/bin, some .h files into ~/include, and some libraries in ~/lib.

To build and install 'sat_id':

cd ~/find_orb/sat_code
make sat_id
make install

For 'find_orb' and 'fo' :

cd ~/find_orb/find_orb
make
make install
cd ~/.find_orb    
wget ftp://ssd.jpl.nasa.gov/pub/eph/planets/Linux/de430t/linux_p1550p2650.430t

(The last two lines put you into Find_Orb's configuration directory and download a JPL ephemeris file there. The file in question is 88 MBytes, and covers years 1550 to 2650. All you have to do is to put the file there; Find_Orb will look for it when it starts up. If you prefer, you can tell Find_Orb to get JPL ephemeris data from a different file. You can even skip this entirely, but the program will run rather slowly; I really don't recommend it.)

ON MULTIPLE-USER MACHINES :

The above installation procedure makes Find_Orb, fo, and other tools available to the user who got the source code and built it. If you have more than one user, you can, instead of make install, run

 sudo make install GLOBAL=Y 

With that, everybody on the machine can run the programs.

With the 'usual' single-user procedure, include files, libraries, and (most crucially from the end user perspective) executables would go into ~/include, ~/lib, and ~/bin respectively. With the GLOBAL=Y option, those files go into /usr/local/include, /usr/local/lib, and /usr/local/bin instead. That makes them available to everybody on that machine. But you do have to sudo to do it.

THE 'MISCELL' PROJECT :

Not everyone will have much need for/interest in the 'miscell' project. It does contain four programs that may prove useful at some point or another :

DIRECTIONS FOR UPDATING ON MACHINES WITH THE SOURCE CODE :

From time to time, as changes are made to the code, you'll have to run some or all of the following :

cd ~/find_orb/lunar
git pull
make
make integrat
make install
cd ~/find_orb/sat_code
git pull
make
make install
cd ~/find_orb/jpl_eph
git pull
make
make install
cd ~/find_orb/find_orb
git pull
make
make install

I say "some or all" because I won't necessarily have updated absolutely everything. If you run 'git pull' and no changes are pulled, you might as well skip 'make' and 'make install'. (The JPL ephemeris and satellite code libraries are pretty darn stable at this point and are rarely updated (though I did have to update the JPL ephemeris library recently to accommodate DE-436 and DE-436t), and the 'lunar' library of basic astronomical functions only gets the occasional update.)

DIRECTIONS FOR COPYING THE SOFTWARE TO OTHER MACHINES THAT LACK THE SOURCE CODE:

(Note that Linux binary compatibility is not absolute, but if you want to copy between roughly similar machines, it'll probably work.)

You should copy the ~/.find_orb directory from the original machine to the other machine(s), and the following from ~/bin (/usr/bin if you installed the software to be available for all users :

astcheck
find_orb
fo
integrat
sat_id

RUNNING INTEGRAT :

The behavior of 'integrat' will be essentially that to which you have become accustomed. You specify an input MPCORB.DAT-formatted file, an output file name, and the epoch to which the elements are to be integrated. Optionally, you can specify the path to a JPL ephemeris file. For example :

integrat MPCORB.DAT new_mpcorb.dat 2017 Jul 13 -z3 -f ~/.find_orb/*.430t

would integrate the given MPCORB.DAT to 2017 July 13, putting the result in 'new_mpcorb.dat'. The computation would be split up over three processes; if you have three or more cores, it'll run about three times faster than it otherwise would have. Planetary positions for the numerical integration will be computed using the same JPL file as was copied above for Find_Orb.

If the output file already exists, Find_Orb assumes you're doing an update. It is bright enough to look through the existing file and say, while reading a (possibly very revised) input: "The following lines didn't change. This object has the same observations and orbit as before. So why bother re-integrating it? Just recycle the previous result."

This is somewhat safer than you might think; the program is conservative about what it's willing to recycle. However, in practice, the recycling can save a lot of time; most orbits don't update all that frequently.

RUNNING SAT_ID :

The way you run this hasn't changed much. The main differences are that it can check multiple sources for possible identifications, and that it uses motion information, instead of just relying on how close your astrometry is to a predicted artsat position. As a result, it can run in an automated fashion: in the tests I ran, it did a basically flawless job of recognizing the artsat astrometry as belonging to artsats, without falsely flagging rocks as artsats.

You can run, for example,

sat_id astrometry.txt -t ~/tles/ALL_TLE.TXT

to have it check astrometry.txt against all satellites in ~/tles/ALL_TLE.TXT. However... as you know, ALL_TLE.TXT just gets you what JSpOC tracks and releases; to fully check artsats, you need data on classified objects and the TLEs that I've produced for high-fliers for which nobody else (as far as I know) produces elements.

I've recently started storing "my" TLEs on GitHub. I would recommend cloning this repository to your home folder, and then running git pull from time to time to get updates. This, of course, has the advantage that git will only grab updates.

If you have git-less machines, as I gather you do, you can either copy ~/tles from one machine to the rest, or download the ZIP-ball from the repository.

Note that the above contains only the TLEs computed by me. You will also need to download the ALL_TLE.TXT file, the integrated classified elements, and the 'full' classified elements, and unZIP them into ~/tles as well.

At that point, if you run

sat_id astrometry.txt -t ~/tles/tle_list.txt

sat_id will check artsats against pretty much everything we know about. (If you look at ~/tles/tle_list.txt, you'll see that about all it does is to list which TLEs ought to be run through.)

I have a cron job to grab ALL_TLE.TXT daily and the classified files weekly. The files I've provided for high-fliers run out for (in most cases) the rest of this year, and longer for some more stable objects.

RUNNING FIND_ORB (AND FO) :

This should be much the same as before, except that the program will look for all configuration and ephemeris files in ~/.find_orb and can be run from anywhere... should be more convenient. Also, Alex mentioned that the program was hanging on some input; I saw that too, a couple of years ago, but haven't seen it in an extra-special long time.

As before, you can run either of

find_orb (input astrometry file)
fo (input astrometry file)

Important tip: Add the -c command line option to either program to "combine" all observations in the file, so they're treated as if they are of a single object. Kinda handy when you're wondering if object X is the same as object Y, and you don't want to have to edit designations.

For fo (but not find_orb), one can add the -p(number) option to tell the program to split the objects over (number) cores. Probably not something you'll need to do; I found it very handy when, say, processing a few hundred thousand objects from the MPC's UnnObs.txt file.

Also fo-only : by default, the output to the screen uses some colors to draw your attention to unusually low MOIDs and comet-like eccentricities and inclinations. This is fine on-screen, but if you direct it to a file, you'll collect escape codes that would confuse anything trying to process the file. Add the -v command line switch to suppress these codes.

(Note to self: dump residuals, in RA/dec and time and cross-track and in magnitude, to a standardized, computer-friendly format suitable for Multicheck and whoever else could use it)

SETTING THE JPL EPHEMERIS FILE

There is some discussion in the Find_Orb documentation on how and why to use JPL ephemeris files in Find_Orb. Note that in Linux, *BSD, and OS/X, you can put a JPL ephemeris file into ~/.find_orb, and the program will find it and use it. That's the simplest way to add a JPL ephemeris file and the default suggestion in the above installation directions.

If you have a JPL ephemeris file in some other folder, and just want to tell Find_Orb to use that instead, I suggest running Find_Orb once without worring about the JPL ephemeris file. (It'll be a little slow.) Then, edit the file ~/.find_orb/environ.dat and look for the line LINUX_JPL_FILENAME=. Above it are some instructions on setting the JPL ephemeris file name.