document updates

.gitignore

@@ -3,6 +3,9 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+#autogenerated slurm scripts
+*.sh
+
 # C extensions
 *.so
 

docs/conf.py

@@ -12,13 +12,12 @@
 
 # Define path to the code to be documented **relative to where conf.py (this file) is kept**
 sys.path.insert(0, os.path.abspath("../src/"))
-from pkg_resources import get_distribution
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 
-copyright = "2023"
+copyright = "2024"
 project = "Sorcha"
 author = "Sorcha development team"
 release = version("sorcha")
@@ -29,7 +28,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx.ext.viewcode"]
+extensions = ["sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinx_exec_directive"]
 
 extensions.append("autoapi.extension")
 extensions.append("nbsphinx")
@@ -40,7 +39,6 @@
 master_doc = "index"  # This assumes that sphinx-build is called from the root directory
 html_show_sourcelink = False  # Remove 'view source code' from top of page (for html, not python)
 add_module_names = False  # Remove namespaces from class/method signatures
-
 autoapi_type = "python"
 autoapi_dirs = ["../src"]
 autoapi_ignore = ["*/__main__.py", "*/_version.py"]

docs/gettingstarted.rst

@@ -71,9 +71,17 @@ will produce
 .. literalinclude:: ./example_files/help_output.txt 
     :language: text
 
-Now that you know how to provide the input files, let's go run a simulation::
+Now that you know how to provide the input files, let's go run a simulation: 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
+
+Or you can in an interactive python session or jupyter notebook. You can run the following
+
+.. exec::
+
+   from sorcha.utilities.sorcha_demo_command import get_demo_command
+   print(get_demo_command())
 
-   sorcha -c ./demo/sorcha_config_demo.ini  -p ./demo/sspp_testset_colours.txt -ob ./demo/sspp_testset_orbits.des -pd ./demo/baseline_v2.0_1yr.db -o ./ -t testrun_e2e -ar ./ar_files 
 
 .. tip::
    Sorcha outputs a log file (*.sorcha.log) and error file (*.sorcha.err) in the output directory. If all has gone well, the error file will be empty. The log file has the configuration parameters outputted to it as a record of the run setup.

docs/index.rst

@@ -65,5 +65,3 @@ works, tutorials, and demonstration notebooks that show how each of the various
    acknowledgements
    cite
    uninstall 
-
-

docs/inputs.rst

@@ -66,9 +66,9 @@ An example of an orbit file in Cometary format::
 +=============+==================================================================================+
 | objID       | Object identifier for each synthetic planetesimal simulated (string)             |
 +-------------+----------------------------------------------------------------------------------+
-| FORMAT      | Orbit format string (COM for heliocentric or BCOM for barycentric)  		         |
+| FORMAT      | Orbit format string (COM for heliocentric or BCOM for barycentric)  		 |
 +-------------+----------------------------------------------------------------------------------+
-| q           | Perihelion (au)	                                                								 |
+| q           | Perihelion (au)	                                                                 |
 +-------------+----------------------------------------------------------------------------------+
 | e           | Eccentricity                                                                     |
 +-------------+----------------------------------------------------------------------------------+

docs/installation.rst

@@ -136,9 +136,16 @@ To install the necessary SPICE auxiliary files for ephemeris generation (774 MB
 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::
+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::
 
-   sorcha -c ./demo/sorcha_config_demo.ini -p ./demo/sspp_testset_colours.txt -ob ./demo/sspp_testset_orbits.des -pd ./demo/baseline_v2.0_1yr.db -o ./ -t testrun_e2e
+   sorcha_demo_command 
+
+Or you can in an interactive python session or jupyter notebook. You can run the following
+
+.. exec::
+
+   from sorcha.utilities.sorcha_demo_command import get_demo_command
+   print(get_demo_command())
 
 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:
 

docs/notebooks.rst

@@ -15,3 +15,5 @@ Notebooks
     Uncertainties and Randomization <notebooks/demo_UncertaintiesAndRandomization>
     Vignetting Demo <notebooks/demo_Vignetting>
     Lightcurve demo <notebooks/demo_Lightcurve>
+    Example Bash Scripts for Multiple Runs <notebooks/demo_GenerateBashScripts>
+    Example Slurm Scripts for Multiple Runs <notebooks/demo_GenerateSLURMScripts>

docs/requirements.txt

@@ -4,15 +4,17 @@ pytest
 pytest-cov
 astropy
 astroquery
+sorcha
 scipy
 sbpy
 matplotlib
 sphinx
 sphinx-rtd-theme
 sphinx-autoapi
+sphinx-exec-directive
 nbsphinx
 ipython
 jupytext
 jupyter
 sorcha-addons
-importlib_resources
+importlib_resources

pyproject.toml

@@ -58,6 +58,7 @@ dev = [
     "pre-commit", # Used to run checks before finalizing a git commit
     "sphinx", # Used to automatically generate documentation
     "sphinx-rtd-theme", # Used to render documentation
+    "sphinx-exec-directive", # running sphinx python commands in documentation
     "sphinx-autoapi", # Used to automatically generate api documentation
     "black", # Used for static linting of files
     # if you add dependencies here while experimenting in a notebook and you
@@ -78,9 +79,10 @@ test = [
 ]
 
 docs = [
-    "sphinx==6.1.3", # Used to automatically generate documentation
-    "sphinx-rtd-theme==1.2.0", # Used to render documentation
-    "sphinx-autoapi==2.0.1", # Used to automatically generate api documentation
+    "sphinx", # Used to automatically generate documentation
+    "sphinx-rtd-theme", # Used to render documentation
+    "sphinx-autoapi", # Used to automatically generate api documentation
+    "sphinx-exec-directive", # running sphinx python commands in documentation
     "nbconvert",
     "nbsphinx",
     "ipython",

src/sorcha/ephemeris/simulation_driver.py

@@ -233,8 +233,8 @@ def get_residual_vectors(v1):
     """
     Decomposes the vector into two unit vectors to facilitate computation of on-sky angles
 
-    Parameters:
-    ----------
+    Parameters
+    -----------
         v1 (array, shape = (3,)):
             The vector to be decomposed
     Returns:

src/sorcha/ephemeris/simulation_setup.py

@@ -36,7 +36,7 @@ def create_assist_ephemeris(args) -> tuple:
     """Build the ASSIST ephemeris object
 
     Returns
-    -------
+    ---------
     Ephem : ASSIST ephemeris obejct
         The ASSIST ephemeris object
     gm_sun : float
@@ -95,8 +95,8 @@ def generate_simulations(ephem, gm_sun, gm_total, orbits_df, args):
     """
     Creates the dictionary of ASSIST simulations for the ephemeris generation
 
-    Parameters:
-    -------
+    Parameters
+    ------------
     ephem (Ephem):
         The ASSIST ephemeris object
     gm_sun (float):
@@ -108,8 +108,8 @@ def generate_simulations(ephem, gm_sun, gm_total, orbits_df, args):
     args (dictionary or `sorchaArguments` object):
         dictionary of command-line arguments.
 
-    Returns:
-    -------
+    Returns
+    ---------
     dict
         Dictionary of ASSIST simulations
 
@@ -168,7 +168,7 @@ def precompute_pointing_information(pointings_df, args, configs):
     with additional information that Assist & Rebound needs for it's work.
 
     Parameters
-    ----------
+    -----------
     pointings_df : pandas dataframe
         Contains the telescope pointing database.
     args : dictionary
@@ -177,7 +177,7 @@ def precompute_pointing_information(pointings_df, args, configs):
         Configuration settings.
 
     Returns
-    -------
+    --------
     pointings_df : pandas dataframe
         The original dataframe with several additional columns of precomputed values.
     """

src/sorcha/utilities/retrieve_ephemeris_data_files.py

@@ -18,7 +18,7 @@ def _decompress(fname, action, pup):
     For instance `filename.json.bz` will be decompressed and saved as `filename.json`.
 
     Parameters
-    ----------
+    ------------
     fname : string
         Original filename
     action : string
@@ -42,7 +42,7 @@ def _remove_files(retriever: pooch.Pooch) -> None:
     list.
 
     Parameters
-    ----------
+    ------------
     retriever : pooch
         Pooch object that maintains the registry of files to download.
     """
@@ -55,19 +55,19 @@ def _remove_files(retriever: pooch.Pooch) -> None:
 
 def _check_for_existing_files(retriever: pooch.Pooch, file_list: list[str]) -> bool:
     """Will check for existing local files, any file not found will be printed
-     to the terminal.
+    to the terminal.
 
-     Parameters
-     ----------
-     retriever : pooch
-         Pooch object that maintains the registry of files to download.
-     file_list : list of strings
-         A list of file names look for in the local cache.
+    Parameters
+    -------------
+    retriever : pooch
+        Pooch object that maintains the registry of files to download.
+    file_list : list of strings
+        A list of file names look for in the local cache.
 
-     Returns
-     -------
+    Returns
+    ----------
     :  bool
-         Returns True if all files are found in the local cache, False otherwise.
+        Returns True if all files are found in the local cache, False otherwise.
     """
 
     # choosing clarity over brevity with these variables.

src/sorcha/utilities/sorcha_demo_command.py

@@ -10,8 +10,8 @@ def get_demo_command():
 
     Returns
     -----------
-    None.
-
+    : string
+        working sorcha demo command
     """
 
     return "sorcha -c sorcha_config_demo.ini -p sspp_testset_colours.txt -ob sspp_testset_orbits.des -pd baseline_v2.0_1yr.db -o ./ -t testrun_e2e"