docs

doc/code_structure.rst

@@ -0,0 +1,88 @@
+Code Organization
+=================
+
+Goals of NEOSpy
+---------------
+NEOSpy is a collection of tools for calculating the orbits and expected fluxes for minor
+planets specifically for the purpose of estimating which objects are visible in current,
+past, or future sky surveys.  Specifically the goal is that these calculations may be
+performed on the full set of all known asteroids in a reasonable amount of time on a
+laptop. 
+
+Propagation
+~~~~~~~~~~~
+There are a number of existing tools which enable the propagation of orbits for
+many millions or billions of years, but these typically are designed for a comparatively
+small number of objects (perhaps 10-100 thousand), whereas NEOSpy's design intent is
+10-100 million objects over the course of decades. The total compute approximately
+scales like::
+
+    computation time ~ (number of objects) x (length of time being simulated)
+
+However solving the large number of objects for a relatively short length of time can be
+optimized differently than a small number of objects for Giga-years.
+
+Flux Estimation
+~~~~~~~~~~~~~~~
+After propagation has been performed, it is important to estimate the total expected
+flux of the objects from the point of view of an observer. There are a number of models
+for this available, including the Near Earth Asteroid Thermal Model (NEATM), the Fast
+Rotator Model (FRM), and the HG-Magnitude system which is common for asteroids in the
+visible band.
+
+SPICE Kernel Interoperability
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SPICE is a commonly used software package which has been in development for several
+decades at this point, and is often used to keep track of the ephemeris of planets,
+satellites (both natural and artificial), asteroids, and comets. Essentially the motion
+of anything in the Solar System can be encoded in some flavor of SPICE kernel. The
+primary downside of using cSPICE is that there is no native support for multi-core cpu
+queries (an artifact of the age of the code). NEOSpy has native multi-core support for
+the majority of all commonly used SPICE kernels.
+
+
+High level Structure
+--------------------
+
+Why Rust?
+~~~~~~~~~
+Given the goals listed above, it is clear that performance plays a key roll in design
+considerations of the tool. As a result of this, the Rust language was chosen as the
+primary language for a majority of the business logic. A Python "wrapper" was written on
+top of the Rust core, allowing users to call the compiled Rust code from Python. This
+wrapper lowers the barrier to entry for users doing data-analysis or simulations without
+having to learn the underlying Rust.
+
+Rust has a number of advantages over existing languages, it's performance is typically
+comparable to C++/C, however due to the structure of the language it is less prone to
+the most common type of errors to do with memory allocation and management. In addition
+to this, Rust has excellent native multi-core support, especially for embarrassingly
+parallel problems such as the orbit propagation required for NEOSpy.
+
+NEOSpy Core
+~~~~~~~~~~~
+The Rust core of the library, which does the underlying orbit and flux calculations is
+written entirely without any reference to Python. This core part is available as
+`neospy_core`, and programming can be done entirely within Rust for tools which do not
+require the Python wrapper. This design was chosen so that systems tools which would
+benefit from orbit computation can be written without having to have Python installed.
+It is important to note that if performance is a concern, then removing the Python is an
+important step to get the maximum possible performance.
+
+Core Python Wrapper
+~~~~~~~~~~~~~~~~~~~
+The Rust library described above then has Python wrappers written over it, allowing
+users to call these compiled tools inside of Python. In order to do this, some
+boiler-plate code is required to glue these independent parts together. This is where
+the `rust` folder inside of NEOSpy comes from. Inside of this folder there are rust
+files which are mostly a one-to-one mapping to their respective counterparts inside of
+the `neospy_core`. Ideally there should be no 'business' logic contained within these
+wrappers, and they should largely exist to provide convenient mappings from the Python
+concepts to the Rust internal organization.
+
+NEOSpy Python
+~~~~~~~~~~~~~
+The remaining part of the code which is strictly Python is mostly quality of life
+functions, plotting, and web query code. There is little to no mathematics or physics
+contained within the Python. The exception being the population related code, which
+manages the fair sampling of the known asteroids to generation synthetic populations.

doc/index.rst

@@ -32,6 +32,8 @@ move out of frame.
    :maxdepth: 2
 
    background
+   code_structure
+   propagation
 
 .. toctree::
    :maxdepth: 1

doc/propagation.rst

@@ -0,0 +1,108 @@
+Orbit Propagation
+=================
+
+Orbit propagation can be an immensely complicated topic, spanning from two-body
+Keplerian motion, to models of gravitational fields including thousands of terms. Being
+able to pick the correct amount of precision required is difficult, and NEOSpy makes a
+number of judicious choices which are reasonable for the vast majority of cases.
+
+What follows is a discussion of the pros-cons of various models of gravitational forces,
+and when the model is "good enough" for the problem at hand.
+
+If we wish to predict the on-sky position or motion of an object, the level of precision
+required depends greatly upon the distance which the object is from the observer.
+Being accurate to 100nm when we are looking 5 au away is not necessary, alternatively, 
+when we are considering an NEO such as Apophis (which will come very close to hitting
+the Earth), meters matter.
+
+.. figure:: images/orbit_models.png
+    :width: 600
+
+    This is a plot of an arbitrary, rather large Main Belt Asteroid, and its orbital
+    propagation error going back 100 years. Specifically error in orbit propagation
+    comparing internal propagation against JPL Horizons SPICE kernels. This compares the
+    difference in position for the two-body approximation, orbit propagation assuming
+    there are no massive asteroids in the main belt, and finally including the 5 most
+    massive main belt asteroids. Note that JPL Horizons includes at least 16 of the
+    largest asteroids, so there is still residual error over the course of 100 years.
+    This error however is only on the order of 100km.
+
+Forces
+------
+
+First it is useful to list out forces which objects in space may experience, to get an
+understanding of what is required in order to accurately model their motion. These are
+listed in approximately the order of their effects on objects (though order may change
+due to varying circumstances).
+
+- *Newtonian Gravity* - Typically what is imagined when people say the force of gravity.
+- *Corrections for Relativity (GR)* - The orbit of Mercury precesses due to effects from 
+    relativity, and in fact many NEOs, or even objects which get close enough to planets
+    will experience effects from relativity.  
+- *Gravity from Minor Planets* - Main belt asteroids are often non-negligible.
+    The motion of objects through the main belt often needs to include the mass of
+    asteroids such as Ceres, which makes up an appreciable fraction of the total mass of
+    the belt.  
+- *Oblateness of the Sun/Planets* - The Sun and Planets are not ideal spheres, and as a
+    result, cannot be exactly modeled as a point source. This non-sphericity can be
+    written as an expansion of spherical harmonic-like terms, commonly written as `J`
+    terms. The first non-trivial term of this expansion is the oblateness, referred to
+    as `J2`. This term by itself will cause objects in orbit of the central mass to
+    have their longitude of ascending node precess as a function of how inclined they
+    are with respect to the equator of the central mass.  
+- *Non-gravitational Forces* - The forces above are a result of gravity, however there
+    are many potential forces which an object may experience, these include things such
+    as outgassing, radiation pressure, the Yarkovsky effect, and the Poynting-Robertson
+    effect. These effects typically have some relation to the total solar radiation that
+    the object is receiving, and can frequently be written as a polynomial with respect
+    to the distance that the object is from the Sun.
+
+
+Accuracy
+--------
+
+Accuracy of the orbit propagation depends on how precisely the forces above are
+computed, and the precision of the numerical integrator used. Forces such as the
+Yarkovsky effect cause relatively small forces on asteroids, but will add up to be
+non-negligible over the course of kilo-year or mega-years. A common issue however is
+that we often don't have accurate enough measurements of the objects to be able to
+accurately measure the contribution of these forces.  
+
+Close encounters with other objects also cause significant accuracy issues as well. The
+force between objects follows a `1/r^2` relationship, meaning as the distance goes to
+zero, small changes in the distance cause large changes in the force. We do not have
+infinitely precise measurements of the objects orbits, meaning there is some positional
+error in our knowledge of every object. This error "blows up" during close encounters
+because of the small `r` effect. Many objects which cross the path of planets frequently
+will have relatively close encounters with planets with some regularity, making long
+term predictions of their orbits difficult. Typically it only takes a few close
+encounters to completely ruin any hope of predicting the position of an object in the
+future or past. This makes the inner solar system a chaotic system in the mathematically
+sense, small deviations of input parameters have large implications for future behavior
+(despite the fact that everything should in theory be precisely computable).  
+
+The result of the problems above, objects in the inner solar system of often very
+difficult to model more than a few hundred/thousand years into the future with any
+accuracy.
+
+Performance
+-----------
+
+To achieve the highest accuracy, all forces listed above must be included. The downside
+for this is that it can be computationally expensive. If we wish to predict the position
+of minor planets for NEOWISE frames as an example, which are captured every 10-15
+seconds, it would be wildly inefficient. Over the course of a few minutes objects motion
+can be modeled as linear, over hours (even days) the two-body approximation is often
+good enough. As a result of this, NEOSpy has tools for adaptively changing the
+approximation used in order to get good computational performance. The typical method is
+to use a full N-Body simulation to get the highest precision, then use that solution for
+the next day or so (adjustable) with two-body mechanics to query hundreds of times.
+
+.. figure:: images/orbit_models_short.png
+    :width: 600
+
+    Demonstration of how quickly linear motion, two-body motion, and N-Body deviate from
+    the true position over the course of a few weeks. Linear motion is invalid within a
+    few minutes, but two-body takes several days for this object to become significantly
+    inaccurate. The dotted black line is how far an object must move tangentially to
+    have an error of 0.1 arcseconds when it is 1 au from the observer (about 74km).