Welcome to the

Comet/asteroid Orbit Determination and Ephemeris Software

Download Site and User's Manual

by Jim Baer

 Thanks to the kind efforts of Andrea Pelloni, Roberto Haver, and Fabio Anzellini, an Italian version of this site is also available

 

Contents:

Introduction

System Requirements

Download and Installation Instructions

How to Start CODES

Background Documentation

Operating Instructions

Where to find data for use in CODES

Notes on numerical integration and the accuracy of CODES

Data Input Errors

Release Information

 

 

Introduction

In support of current astronomical surveys for minor planets, CODES combines an n-body numerical integrator with a Graphical User Interface to provide the following capabilities:

  • calculate the state vector/orbital elements (with covariances) of a comet or asteroid, based on up to 1000 optical and radar observations;
  • identify known minor planets that most closely fit the observations of a comet or asteroid;
  • calculate topocentric or geocentric ephemerides, based either on calculated, user-specified, or imported MPC state vector/orbital elements;
  • linear and non-linear analysis of collisions/near-misses between a minor planet and the nine major planets (plus Earth’s Moon) through 2200;
  • account for cometary thrusting (if applicable), solar radiation pressure, solar oblateness, and gravitational perturbations (including relativistic effects) from the Sun, nine planets, Earth's Moon, and up to 300 asteroids.

 

System Requirements

  • approximately 150 MB of disk storage
  • Java 1.4.1 (or higher) runtime environment (see Download and Installation Instructions)
  • suggested RAM - 256 MB or greater
  • narrowband or broadband internet access (for download of observation files and updated CODES data files)

 

Download and Installation Instructions

The CODES application is written in Pure Java; that is, the source code contains no commands specific to any particular operating system. As a result, compiled Java source code (known as "bytecode") can be run on any operating system.

In order to achieve Java's universality, Sun Microsystems has created a Java Virtual Machine (VM) to run on top of each popular operating system. The VMs provide a standard reference platform for the bytecode, translating it into processor-specific assembly code, which is then executed.

Thus, in order to run a compiled Java application such as CODES, a user must install the Java Runtime Environment (JRE) specific to their operating system, consisting of the VM and a "Just-in-Time" compiler that substantially accelerates bytecode processing.

The Java Runtime Environment, and instructions for installation, can be downloaded from Sun's web site.

To download and install CODES, the user should

  1. Create a new folder (Windows users) or directory (Solaris, Unix or Linux users) named "codes"
  2. Download the following files from this web site to the "codes" folder/directory:

Important Note: As the Minor Planet Center certifies new contributing observatories, they must be added to the "ObsCode" file to support accurate processing of MPC and NEODyS observation files; users are therefore advised to return to this web site (at least) monthly for updated versions of the "ObsCode" file.

Important Note: I would strongly urge users of this most recent version of CODES to install and use the Java 1.4.1 (or later) runtime environment (JRE).  Due to a recent change in the Java compiler, users with the Java 1.3 (or earlier) runtime environment may experience difficulty running the bytecode provided above (which was compiled in a 1.4.1 environment). In short, the source code is still perfectly valid, but the method by which font-related source code commands are compiled into bytecode has changed in Java 1.4.1; as a result, the corresponding 1.4.1 bytecode would not be interpreted correctly in a 1.3 (or earlier) environment.  Users may also elect to recompile the source code provided above in their 1.3 (or earlier) JDK environment; the classes should be compiled in the following "top-down" order: CelestialBody, SolarSystemBody, MinorPlanet, and finally, GUI.

Important note: To support accurate processing of MPC and NEODyS observation files, CODES accounts for the number of leap seconds at the time of each observation. Additional leap seconds are added only as irregular changes in the Earth's rotation warrant; moreover, by convention, any additional leap seconds are added only on the 30'th of June or the 31'st of December of a given year (none planned for 31 Dec 2002). Users are therefore advised to return to this web site for updated versions of the CelestialBody file whenever additional leap seconds are announced.

Important note for Solaris/Unix/Linux users: The file "GUI$1.class" may be renamed "GUI_1.class" during download. If this occurs, please rename it as "GUI$1.class" so the Java Runtime Environment can find it.

  1. Download the following DE405 planetary ephemeris files (ASCII versions) from the JPL web site to the "codes" folder/directory:
    • ASCP1900.405 (save to disk as "ASCP1900.txt")
    • ASCP1920.405 (save to disk as "ASCP1920.txt")
    • ASCP1940.405 (save to disk as "ASCP1940.txt")
    • ASCP1960.405 (save to disk as "ASCP1960.txt")
    • ASCP1980.405 (save to disk as "ASCP1980.txt")
    • ASCP2000.405 (save to disk as "ASCP2000.txt")
    • ASCP2020.405 (save to disk as "ASCP2020.txt")
    • ASCP2040.405 (save to disk as "ASCP2040.txt")
    • ASCP2060.405 (save to disk as "ASCP2060.txt")
    • ASCP2080.405 (save to disk as "ASCP2080.txt")
    • ASCP2100.405 (save to disk as "ASCP2100.txt")
    • ASCP2120.405 (save to disk as "ASCP2120.txt")
    • ASCP2140.405 (save to disk as "ASCP2140.txt")
    • ASCP2160.405 (save to disk as "ASCP2160.txt")
    • ASCP2180.405 (save to disk as "ASCP2180.txt")
  1. Download the following MPC orbital element files and save them to the "codes" folder/directory, renaming them as listed:

Note: If the user chooses to download the zipped version of MPCORBcr, simply unzip the file and save it to the "codes" folder/directory, renaming it as "MPCORBcr.DAT".

 

How to Start CODES

  • (Windows 95/98/2000/NT/XP)
    1. From the Start button, select Programs -> MS-DOS Prompt
    2. Type "cd c:\codes" to change to the "codes" folder, which contains the above downloaded files
    3. Type "java -Xmx200m GUI"  (Note: The "-Xmx200m" portion of the command increases maximum heap space from 64 MB to 200 MB)
    4. Begin at the CODES Welcome Screen
  • (Solaris/Unix/Linux)
    1. Change to the "codes" directory, which contains the above downloaded files
    2. Type "java -Xmx200m GUI"  (Note: The "-Xmx200m" portion of the command increases maximum heap space from 64 MB to 200 MB)
    3. Begin at the CODES Welcome Screen

Note: When CODES is run for the first time, users may notice the following error message: "Error -- java.io.FileNotFoundException: minor_planet_list (No such file or directory)". You should nevertheless be able to proceed.

The "minor_planet_list" normally contains the list of comets and asteroids that have been added to CODES; as such, when the user hits "Begin" and enters the Level One Menu, CODES will try to read the file so as to provide the user with the list of available minor planet files to edit (or delete). Since none yet exist, the error message results.  Once the user creates a minor planet, the "minor_planet_list" file will be created, and the error message should not recur.

 

Background Documentation

The requirements document and dynamical model are also available. I would recommend reading them before proceeding further, as they give an overview of the capabilities of the software, and the design of its Graphical User Interface.

 

Operating Instructions

CODES was designed and written as an object-oriented application. The general idea, therefore, is to create an instance of the Minor Planet class (e.g. asteroid 1997 XF11), specify some attributes (e.g. optical and/or radar observations), and execute various functions or operations (e.g. compute initial and best-fit orbit, check for collision/near-miss) that will generate the values of additional attributes (state vector/orbital elements, absolute magnitude, estimated radius). Following valid data entry or the successful completion of operations, the file for the subject minor planet, containing the values of all attributes, is saved to disk.

The application has a two-tiered menu.

The Level One Menu allows the user to select whether to

  • create new instances of minor planets;
  • edit the attributes of, or conduct operations on, existing minor planets; or
  • delete existing minor planets.

The Level Two Menu provides the graphical interface allowing the user to specify the attributes of a particular minor planet and conduct various operations.   From any subsequent screen, it is possible to cancel (or end) the current function and return to the Level Two Menu. 

Begin at the Welcome screen by clicking on "Begin"

Simply enter the desired name in the text field and press "Create".

The name you specify will become the name of the data file storing that minor planet's attributes (observations, orbital elements, etc.). Thus, there are Java language restrictions on permissible characters. All alphanumeric characters are permitted, but slashes ("/") and empty spaces (" "), for example, are not permitted. Once the user clicks on "Create", CODES will examine the proposed name and remove any illegal characters. My general guidance, therefore, would be that the user should feel free to use whatever name, number, or provisional designation is desired or appropriate; CODES will remove any illegal characters as needed.

The user will then have the option of returning to the Level One Menu, or continuing on to edit the newly created minor planet from the Level Two Menu.

The advanced user also has the option of executing an "Expedited Comparison".  CODES will assume that both an mpec.txt observation file for this minor planet and a current copy of MPCORBcr.DAT are available in the "codes" folder; CODES will process the observations, add them to the minor planet's data file, and determine which known single-opposition NEAs best match these observations (using medium-accuracy numerical integration).  Note that this option should be used with care, since the absence of the appropriate version of either file from the "codes" folder will result in a crash. 

This option allows the user to select a particular pre-existing minor planet, and add attribute data (i.e., specify optical or radar observations) or perform operations (e.g., compute the orbit, check for collisions/near-misses).

Simply select the desired entry from the drop-down menu and press "Edit". This will take the user to the Level Two Menu.

Simply select the desired minor planet from the drop-down menu and press "Delete". The file associated with the selected minor planet is deleted.

The user may then return to the Level One Menu.

 

  • Level Two Menu - Specifying attributes of, and executing operations on, the subject minor planet

For several operations (e.g., processing visual magnitude data, looking for known bodies whose positions agree with the observations of the subject minor planet), it is critical that CODES understand whether the subject minor planet is a comet or an asteroid.

Thus, this designation should be made immediately upon creating a new minor planet.

From the Level Two Menu, simply click on "Designate"; on the resulting frame, select whether the minor planet is a comet or asteroid, then click on "Submit".

The designation being made, CODES will save the data to disk and return to the Level Two Menu.

From the Level Two Menu, simply click on "Add". From the resulting frame, the user can then select from the following options:

Simply click on "Optical". The user will then encounter three successive frames:

The first frame allows the user to specify the UTC date of the optical observation, the astrometric right ascension and declination (with uncertainties), the visual magnitude, and the fundamental catalog/epoch to which the observation refers.

Note: CODES supports observations and predictions for the range 1900-2200.

The second frame allows the user to specify either the MPC observatory code, or the geodetic latitude, east longitude, and altitude, from which the observation was made. Additionally, the user may check a box telling CODES to generate default Earth Orientation Parameters; the third frame would then be skipped.

Note: For typical optical observations, where uncertainties are on the order of 0.1 arc seconds or greater, the default EOPs generated by CODES are sufficient.

The third frame allows the user to specify the Earth Orientation Parameters (EOPs) at the time of the observation. EOPs allow calculation of the ultra-precise location of the observer. These EOPs include the x and y coordinates of the Celestial Ephemeris Pole, the values of UT1-UTC, and the Celestial Pole Offsets dPsi and dEpsilon. (Note that these EOPs are required for four dates surrounding the observation; Besselian interpolation is then used to approximate the values of the EOPs at the precise observation time.) Additionally, the user must specify the number of leap seconds and the Earth's angular velocity at the time of observation.

Note: The option to specify EOPs for optical observations will allow future support of more precise astrometric techniques.

Note: An excellent source of EOPs is the International Earth Rotation Service (IERS) web site.

IMPORTANT: Do not leave any data fields blank! This can cause a run-time error.

IMPORTANT: From either of the three input frames, it is possible to cancel the input function and return to the Level Two Menu; the new (and incomplete) observation will be deleted. 

When complete, CODES will save the data to disk and return to the Level Two Menu.

Simply click on "Radar". The user will then encounter three successive frames:

The first frame allows the user to specify the UTC time of observation, whether this observation is a delay or a doppler measurement, the measurement and its uncertainty, and the transmitter frequency.

Note: CODES supports observations and predictions for the range 1900-2200.

The second frame allows the user to specify the location of both the transmitter site and the receiver site. In each case, the user may either select one of several common radar sites (in which case the lat/long/alt data fields may safely be left blank), or select "other" and specify the geodetic latitude, east longitude, and altitude of the transmitter/receiver.

The third frame allows the user to specify the Earth Orientation Parameters (EOPs) at the time of the observation. EOPs allow calculation of the ultra-precise location of the observer. These EOPs include the x and y coordinates of the Celestial Ephemeris Pole, the values of UT1-UTC, and the Celestial Pole Offsets dPsi and dEpsilon. (Note that these EOPs are required for four dates surrounding the observation; Besselian interpolation is then used to approximate the values of the EOPs at the precise observation time.) Additionally, the user must specify the number of leap seconds and the Earth's angular velocity at the time of observation.

Note: For radar data, accuracies of 0.1 microsecond or 30 meters are typical. My sensitivity analyses indicate that 1 meter accuracy could be supported without interpolating the published EOPs. However, the state-of-the-art is advancing so rapidly that I feel it prudent to accommodate future radar technology (up to 0.1 meter accuracy); thus, second-order interpolation of the EOPs is used.

Note: An excellent source of EOPs is the International Earth Rotation Service (IERS) web site.

IMPORTANT: Unless otherwise noted, do not leave any data fields blank! This can cause a run-time error.

IMPORTANT: From either of the three input frames, it is possible to cancel the input function and return to the Level Two Menu; the new (and incomplete) observation will be deleted. 

When complete, CODES will save the data to disk and return to the Level Two Menu.

The Minor Planet Center (MPC) provides free web-based electronic circulars containing formatted tables of new observations of recently discovered and high-interest minor planets. The MPC also provides an Extended Computer Service called MPCOBS which enables users to extract files containing all observations of a specific minor planet.

With some help from the user, CODES can batch-process the entire set of observations contained in each of these files, thus avoiding the need for manual input.

Simply click on "MPC". The next frame will ask the user to save the MPEC or MPCOBS file (from the web browser o