doc updates

updates to overview, installation, citation page, and ephemeris generation,

docs/cite.rst

@@ -19,6 +19,7 @@ Please also cite the software and ancillary data files that helps power Sorcha:
 * assist https://assist.readthedocs.io/en/latest/
 * astropy https://www.astropy.org/acknowledging.html
 * healpy https://healpy.readthedocs.io/en/latest/
+* importlib_resources https://github.com/python/importlib_resources 
 * matplotlib https://matplotlib.org/stable/users/project/citing.html
 * Minor Planet Center https://www.minorplanetcenter.net/data
 * numba https://numba.pydata.org/ 

docs/conf.py

@@ -44,5 +44,5 @@
 autoapi_ignore = ["*/__main__.py", "*/_version.py"]
 autoapi_add_toc_tree_entry = False
 autoapi_member_order = "bysource"
-
+smartquotes = False 
 html_theme = "sphinx_rtd_theme"

docs/ephemerisgen.rst

@@ -12,7 +12,16 @@ Sorcha's ephemeris generator is powered by `ASSIST  <https://assist.readthedocs.
 How It Works
 --------------------------------------------------------
 
-The Sorcha ephemeris generator determines which objects will appear in or near the camera field of view (FOV) for any given exposure.  It uses spatial indexing to speed up these calculations.  It runs through the survey visits and does on-the-fly checks of where every synthetic object is near the center of each night for which there are visits and organizes those positions using the `HEALPix (Hierarchical Equal Area isoLatitude Pixelation of a sphere) <https://healpix.sourceforge.io/>`_ tesselation of the sky.  Given that information, it then steps through the visits for that night, doing precise calculations for just those objects that are near the camera FOV (field-of-view) of each survey on-sky visit.   Specifically, for each visit, the generator calculates the unit vector from the observatory's location to the RA/Dec location of the field center. Then it finds the  set of HEALPix tiles that are overlapped by the survey vist's camera FOV (nside=64). The ephemeris generator then collects the IDs for the particles in the HEALPix tiles overlapped by the given survey visit FOV.  It then does light time corrected ephemeris calculations for just those, outputting the right ascension, declination, rates, and relevant distances, and phase angle values for each of the particles. 
+The Sorcha ephemeris generator determines which objects will appear in or near the camera field-of-view (FOV) for any given exposure.  It uses spatial indexing to speed up these calculations.  It runs through the survey visits and does on-the-fly checks of where every synthetic object is near the center of each night for which there are visits and organizes those positions using the `HEALPix (Hierarchical Equal Area isoLatitude Pixelation of a sphere) <https://healpix.sourceforge.io/>`_ tesselation of the sky.  Given that information, it then steps through the visits for that night, doing precise calculations for just those objects that are near the camera FOV of each survey on-sky visit. Specifically, for each visit, the generator calculates the unit vector from the observatory's location to the RA/Dec location of the field center. Then it finds the  set of HEALPix tiles that are overlapped by the survey vist's camera FOV (nside=64). The ephemeris generator then collects the IDs for the particles in the HEALPix tiles overlapped by the given survey visit FOV.  It then does light time corrected ephemeris calculations for just those, outputting the right ascension, declination, rates, and relevant distances, and phase angle values for each of the particles. 
+
+A cartoon schematic of ephemeris generation within Sorcha for a patch of sky and a single survey observation is shown below. Each box represents a healpixel in the healpix grid on the sky. The colored healpixels are where  different solar system objects is estimated to cover during some part of the night (based on their speed and velocity vector on sky they will be in one or more healpixels) based on the rough calculation from Sorcha. The midnight position and 2 other positions during each night are calculated for each simulated small body. Using interpolation, all the healpixels that the object passes through in the evening are identified. In the figure, each color represents a different moving object on a different orbit. Slower moving objects will cover less healpixels. The green circle represents an area slightly bigger than the survey's camera footprint. For the given observation time, any orbits with healpixels within the circle are integrated to calculate their exact positions at the time of the observation. Those orbits that land within the circle are then identified and the resulting ephemerides associated with those objects and the observation are saved. 
+
+
+.. image:: images/ephemeris_generation.png
+  :width: 500
+  :alt: An overview of Sorcha's ephemeris generation
+  :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. 
 

docs/index.rst

@@ -13,7 +13,7 @@
 What is Sorcha?
 =========================================================================
 
-Sorcha (pronounced "surk-ha") is an open source  Solar System survey simulator written in Python. 
+Sorcha (pronounced "surk-ha") is an open-source Solar System survey simulator written in Python. 
 Sorcha means light or brightness in Irish and Scots Gaelic. Sorcha estimates the brightness of
 simulated Solar System small bodies and determines which ones the survey could detect in
 each of the survey's observations  based on user set criteria. Sorcha has been designed 

docs/installation.rst

@@ -11,20 +11,21 @@ Requirements
 
 Sorcha has the following requirements that will be automatically installed  using pip or conda when you install the sorcha package:
 
-* python 3.9 or later
-* numpy
-* pandas
-* numba
-* scipy
+* python 3.10 or later
+* assist
 * astropy
+* healpy
+* importlib_resources
 * matplotlib
-* sbpy
+* numba
+* numpy
+* pandas
+* pooch
 * pytables
-* spiceypy
-* healpy
-* assist
 * rebound
-* pooch
+* sbpy
+* scipy
+* spiceypy
 * tqdm
 
 .. tip::
@@ -39,14 +40,14 @@ Setup Your Conda Environment
 
 If using conda::
 
-   conda create -n sorcha -c conda-forge assist numpy numba pandas scipy astropy matplotlib sbpy pytables spiceypy healpy rebound pooch tqdm h5py python=3.10 
+   conda create -n sorcha -c conda-forge assist numpy numba pandas scipy astropy matplotlib sbpy pytables spiceypy healpy rebound pooch tqdm h5py importlib_resources python=3.10 
 
 If using mamba::
 
-   mamba create -n sorcha -c conda-forge assist numpy numba pandas scipy astropy matplotlib sbpy pytables spiceypy healpy rebound pooch tqdm h5py python=3.10
+   mamba create -n sorcha -c conda-forge assist numpy numba pandas scipy astropy matplotlib sbpy pytables spiceypy healpy rebound pooch tqdm h5py importlib_resources python=3.10
 
 .. tip::
-   We recommend using python version 3.9 or higher with Sorcha. The conda command uses python 3.10.
+   We recommend using python version 3.10 or higher with Sorcha. The conda command uses python 3.10.
 
 **Step 2** Activate your conda/mamba environment
 
@@ -75,68 +76,40 @@ You can install sorcha via from pypi using pip, but installation via  conda/mamb
 
 If using pip::
 
-   pip install --upgrade sorcha
-
-.. _dev_mode:
-
-Installing Sorcha in Development Mode
----------------------------------------------------------------------
-
-.. tip::
-   This is in the installation method for adding/edit Sorcha's codebase or for working on/updating Sorcha's documentation. 
-
-**Step 1** Create a directory to contain the Sorcha repos::
-
-   mkdir sorcha
-
-**Step 2** Navigate to the directory you want to store the Sorcha source code in::
-
-   cd sorcha
-   
-**Step 3** Download the Sorcha source code via::
-
-   git clone https://github.com/dirac-institute/sorcha.git
-
-**Step 4** Navigate to the sorcha repository directory::
-
-   cd sorcha
-   
-**Step 5** Install an editable (in-place) development version of Sorcha. This will allow you to run the code from the source directory.
-
-If you just want the source code installed so edits in the source code are automatically installed::
-
-   pip install -e .
-
-If you are going to be editing documentation or significantly modifying unit tests, it is best to install the full development version::
-
-   pip install -e '.[dev]'
-
-**Step 6 (Optional unless working on documentation):** You will also install the pandoc package (either via conda/pip or `direct download <https://pandoc.org/installing.html>`_ .
-
+   pip install sorcha
 
 .. _installation_aux:
 
 Downloading Required Supplemental Files
 ----------------------------------------
 
-To run the internal ephemeris generator, you will need to download the auxiliary files required by  assist and rebound for performing the N-body integrations. 
+To run Sorcha's built in :ref:`ephemeris generator<ephemeris_gen>`, you will need to download the auxiliary files required by  assist and rebound for performing the N-body integrations. 
 
-To install the necessary SPICE auxiliary files for ephemeris generation (774 MB total in size)::
+To install the necessary `SPICE (Spacecraft, Planet, Instrument, C-matrix, Events) <https://naif.jpl.nasa.gov/naif/spiceconcept.html>`_ auxiliary files and other required data files for ephemeris generation (774 MB total in size)::
 
     sorcha_bootstrap_data_files
 
 .. note::
-   This script will download and store the auxiliary files in your computer's local cache directory. 
+   This script will download and store the auxiliary files in your computer's local cache directory by default. 
 
 .. note::
-   These files are stored in your system's cache by default if the optional --cache flag is not provided. If the files already downloaded and want a fresh download, you need to use the -f flag. 
+   The optional --cache flag allows you to specify a specific location to download the auxillary files. If the files have  already downloaded and want a fresh download, you need to use the -f flag. 
 
 .. warning:: These files can change/be updated with the revised positions of the planets every once in a while. So if you're running simulations for population statistics, we recommend downloading these files to a directory and having all Sorcha runs these files for consistency. 
 
 Testing Your Sorcha Installation
 ----------------------------------
 
-You can check that the Sorcha installation was done correctly, by downloading the Sorcha source code repository (Steps 1-4 **only**  of :ref:`dev_mode`) and then running the demo command. You can find the command to run the sorcha demo on the command line in two ways. First on the command line::
+You can check that the Sorcha installation was successful, by obtaining the demo input files and running the demo command. 
+
+The demo input files and configuration file are installed with the socha package. You can run the following command on the command line to copy the files to the current directory (or a different location)::
+
+    sorcha_copy_demo_files
+
+.. note::
+   The optional -p flag allows you to specify a specific location to copy the demo input files. If the files already exist, the  -f flag can be used to force a fresh copy of the files to be generated. .
+
+You can find the command to run the sorcha demo on the command line in two ways. First on the command line::
 
    sorcha_demo_command 
 
@@ -146,12 +119,55 @@ Or you can in an interactive python session or jupyter notebook. You can run the
 
    from sorcha.utilities.sorcha_demo_command import get_demo_command
    print(get_demo_command())
+
+.. note::
+   The demo command assumes that the demo input files are in the local directory.
+
+.. tip::
+   If the auxillary files are installed in a different location you will need to specify their location using the --ar flag
 
-The output will appear in a csv file (testrun_e2e.csv) in your current directory. The first 51 lines of the csv file should look like this:
+The output will appear in a csv file (testrun_e2e.csv) in your current directory. The first 51 lines of the csv file should look like this (because of the random number generation the values will not be exactly the same):
 
 .. literalinclude:: ../docs/example_files/testrun_e2e.csv
     :language: text
     :lines: 1-51
 
-.. note::
-   This test run is using pre-generated ephemeris already stored in the demo directory of the Sorcha GitHub repository. 
+.. tip::
+   Two log files will be created in the current directory. One \*.log and one \*.err. The \*.err log file should be empty if all run successfully. 
+
+.. _dev_mode:
+
+Installing Sorcha in Development Mode
+---------------------------------------------------------------------
+
+**This is the installation method for adding/edit Sorcha's codebase or for working on/updating Sorcha's documentation.**
+
+**Step 1** Create a directory to contain the Sorcha repos::
+
+   mkdir sorcha
+
+**Step 2** Navigate to the directory you want to store the Sorcha source code in::
+
+   cd sorcha
+  
+**Step 3** Download the Sorcha source code via::
+
+   git clone https://github.com/dirac-institute/sorcha.git
+
+**Step 4** Navigate to the sorcha repository directory::
+
+   cd sorcha
+  
+**Step 5** Install an editable (in-place) development version of Sorcha. This will allow you to run the code from the source directory.
+
+If you just want the source code installed so edits in the source code are automatically installed::
+
+   pip install -e .
+
+If you are going to be editing documentation or significantly modifying unit tests, it is best to install the full development version::
+
+   pip install -e '.[dev]'
+
+**Step 6 (Optional unless working on documentation):** You will also install the pandoc package (either via conda/pip or `direct download <https://pandoc.org/installing.html>`_ .
+
+