update ephemeris generation and inputs page

update ephemeris generation and inputs page

docs/configfiles.rst

@@ -45,19 +45,3 @@ The source code is available `here <https://github.com/dirac-institute/sorcha/bl
     :linenos:
 
 
-.. _database_query:
-
-Setting Up the Correct LSST Pointing Database Query
----------------------------------------------------
-
-Sorcha's **ppsqldbquery** config file parameter contain the sql query for obtaining this information from the pointing database.
-
-From rubin_sim v2.0 simulations onward use the query::
-
-  SELECT observationId, observationStartMJD as observationStartMJD_TAI, visitTime, visitExposureTime, filter, seeingFwhmGeom, seeingFwhmEff, fiveSigmaDepth, fieldRA, fieldDec, rotSkyPos FROM observations order by observationId
-
-For past rubin_sim/OpSim simulations pre-v2.0 use the query::
-
-  SELECT observationId, observationStartMJD as observationStartMJD_TAI, visitTime, visitExposureTime, filter, seeingFwhmGeom, seeingFwhmEff, fiveSigmaDepth, fieldRA, fieldDec, rotSkyPos FROM SummaryAllProps order by observationId
-
-

docs/ephemerisgen.rst

@@ -23,6 +23,7 @@ A cartoon schematic of ephemeris generation within Sorcha for a patch of sky and
   :align: center
 
 
+
 Because ASSIST uses REBOUND's `IAS15 integrator <https://ui.adsabs.harvard.edu/abs/2015MNRAS.446.1424R/abstract>`_, which has an adaptive time step, Sorcha's ephemeris generator instantiates a REBOUND n-body simulation for each individual massless synthetic object including the effects of the Sun, planets, Moon, and 16 asteroids (see the :ref:`MAP` section). It also includes the J2, J3, and J4 gravitational harmonics of the Earth, the J2 gravitational harmonic of the Sun, and general relativistic correction terms for the Sun, using the Parameterized Post-Newtonian (PPN) formulation. The positions of the massive bodies come from the latest `DE441 <https://iopscience.iop.org/article/10.3847/1538-3881/abd414>`_ ephemeris, provided by NASA's `Navigation and Ancillary Information Facility (NAIF) <https://naif.jpl.nasa.gov/naif/credit.html>`_. We note that the coordinate frame for ASSIST+REBOUND  is the equatorial International Celestial Reference Frame (ICRF).  The positions and velocities are barycentric within this frame, rather than heliocentric. The ephemeris generator translates the input barycentric or heliocentric orbits into x,y, z and velocities into the barycentric ICRF to be read into ASSIST. 
 
 .. tip::
@@ -57,22 +58,36 @@ Here's the list of asteroid pertubers that are included in the ASSIST+REBOUND in
 .. warning::
   If you simulate the orbits of these select asteroids you will get **POOR results** with the internal Sorcha ephemeris generator because of how the n-body integration is setup. We recommend getting the positions of these asteroids from some other source and inputting them as an external ephemeris file. 
 
+.. _tuneem:
+
 Tuning the Ephemeris Generator
 -----------------------------------
 
 There are several tunable options for the ephemeris generation which are described below that are set by the Sorcha :ref:`configs`.
 
-- **Minor Planet Center (MPC) observatory code for the provided telescope**
-- **Field of view of our search field (in degrees)**
-- **Buffer zone around the field of view we want to include (in degrees)**
-- **Picket length (in days)** 
-- **Order of healpix used by healpy**
+- **Minor Planet Center (MPC) observatory code for the provided telescope (ar_obs_code configuration parameter)**
+- **Field of view of our search field (in degrees) (ar_ang_fov configuration parameter)**
+- **Buffer zone around the field of view we want to include (in degrees) (ar_fov_buffer configuration parameter)**
+- **Picket length (in days) (ar_picket configuration parameter)** 
+- **Order of healpix used by healpy (ar_healpix_order configuration parameter)**
+
+To use Sorcha's internal ephemeris generation engine, the configuration file should contain::
+
+   [INPUT]
+   ephemerides_type = ar
+
+   [SIMULATION]
+   ar_ang_fov = 2.06
+   ar_fov_buffer = 0.2
+   ar_picket = 1
+   ar_obs_code = X05
+   ar_healpix_order = 6
 
 .. tip::
-   We recommend you use the defaults value that we use in our :ref:`example_configs` as they are sufficient for most Solar System populations you'll want to simulate. 
+   We recommend you use these default value above that we use in our :ref:`example_configs` as they are sufficient for most Solar System populations you'll want to simulate for LSST observations.
 
-Auxiliary Files 
------------------
+Required Auxiliary Files 
+---------------------------
 
 A number of auxiliary file available from the `Minor Planet Center <https://www.minorplanetcenter.net/data>`_ and  `NASA's Navigation and Ancillary Information Facility (NAIF) <https://naif.jpl.nasa.gov/pub/naif/generic_kernels/>`_ are required for ephemeris generation:
 
@@ -87,3 +102,34 @@ A number of auxiliary file available from the `Minor Planet Center <https://www.
 .. tip::
   See our :ref:`installation_aux` instructions to find out how to download and install these auxiliary files automatically using our download utility. 
 
+Saving the Output From the Ephemeris Generator
+------------------------------------------------
+
+If you want to use the same input orbits across multiple Sorcha runs, you can save time by outputting the output from the epehmeris generation stage using the command line flag **-ew**. Then in subsequent runs you willneed to use the **-er** flag to on the command line to specify the input ephemeris file to read in. You will also need to remove :ref:`the ephemeris generation parameters<tuneem>` from the configuration file and add the following::
+
+   [INPUT]
+   ephemerides_type = external
+   eph_format = csv
+
+
+.. attention::
+   Currently the Sorcha-generated ephemeris is outputted in CSV file format only.
+
+
+
+Providing Your Own Ephemerides 
+---------------------------------
+
+If you prefer to use a different method or software package for producing the ephemerides of your input orbits, you can provide an input file on the command line. Further details be found on the :ref:`Inputs page<ephemf>`. You will also need to set up the configuration file as::
+
+   [INPUT]
+   ephemerides_type = external
+   eph_format = csv
+
+**eph_format** is the format of the user provided ephemeris file. Options are **csv**, **whitespace**, and **hdf5** 
+
+.. tip::
+   Use the **-er** flag on the command line to specify the external ephemeris file that Sorcha should use. 
+
+.. warning::
+   We have validated and tested Sorcha and its internal ephemeris generator. If the user decides to use a different method to provide the required ephemerides for their science, it is up to the user to validate/check the output of the external ephemeris generator. 

docs/inputs.rst

@@ -245,7 +245,25 @@ The latest version of rubin_sim cadence simulations can be found at https://s3df
   :align: center
 
 .. attention::
-   There may be changes to how this information is read in when the Rubin Observatory operations begin in ~mid-2025.
+   There may be changes to how this information is read in when the Rubin Observatory operations begin in the ~end of-2025/early 2026.
+
+
+.. _database_query:
+
+Setting Up the Correct LSST Pointing Database Query
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sorcha's **ppsqldbquery** config file parameter contain the sql query for obtaining this information from the pointing database.
+
+From rubin_sim v2.0 simulations onward use the query::
+
+  SELECT observationId, observationStartMJD as observationStartMJD_TAI, visitTime, visitExposureTime, filter, seeingFwhmGeom, seeingFwhmEff, fiveSigmaDepth, fieldRA, fieldDec, rotSkyPos FROM observations order by observationId
+
+For past rubin_sim/OpSim simulations pre-v2.0 use the query::
+
+  SELECT observationId, observationStartMJD as observationStartMJD_TAI, visitTime, visitExposureTime, filter, seeingFwhmGeom, seeingFwhmEff, fiveSigmaDepth, fieldRA, fieldDec, rotSkyPos FROM SummaryAllProps order by observationId
+
+
 
 .. _CPP:
 
@@ -261,6 +279,8 @@ The complex physical parameters file is only needed if you're going to include y
   *  The complex physical parameters file can be either **white space separated** or **comma value separated (CSV)**
   *  Each simulated object **must** have a unique string identifier
 
+.. _ephemf:
+
 Ephemeris File (Optional)
 -----------------------------------------