From cec7c683ac0226bad2eaf7c87540be5607be4531 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20B=C3=A1nffy?= Date: Thu, 23 Nov 2023 18:26:03 +0000 Subject: [PATCH 1/3] Typo/trailing whitespace fixes --- docs/cite.rst | 2 +- docs/complexparameters.rst | 4 ++-- docs/ephemerisgen.rst | 10 ++++----- docs/gettingstarted.rst | 18 +++++++-------- docs/index.rst | 4 ++-- docs/inputs.rst | 46 +++++++++++++++++++------------------- docs/installation.rst | 12 +++++----- docs/outputs.rst | 2 +- docs/overview.rst | 6 ++--- docs/support.rst | 10 ++++----- docs/troubleshooting.rst | 2 +- 11 files changed, 58 insertions(+), 58 deletions(-) diff --git a/docs/cite.rst b/docs/cite.rst index deb849f1..de94c0f3 100644 --- a/docs/cite.rst +++ b/docs/cite.rst @@ -29,7 +29,7 @@ Please also cite the software and ancillary data files that helps power Sorcha: * rebound https://rebound.readthedocs.io/en/latest/ * sbpy https://joss.theoj.org/papers/10.21105/joss.01426 * scipy https://scipy.org/citing-scipy/ -* SPICE kernels and anscillary data files https://naif.jpl.nasa.gov/naif/credit.html +* SPICE kernels and ancillary data files https://naif.jpl.nasa.gov/naif/credit.html * spiceypy https://spiceypy.readthedocs.io/en/main/citation.html * tqdm https://tqdm.github.io/ diff --git a/docs/complexparameters.rst b/docs/complexparameters.rst index 4df493c9..a90c07e0 100644 --- a/docs/complexparameters.rst +++ b/docs/complexparameters.rst @@ -2,7 +2,7 @@ Incorporating Rotational Light Curves and Active Objects ========================================================== Sorcha has the ability user provided functions though python classes that augment/change the apparent brightness calculations for the synthetic Solar System objects. Any values required as input for these calculations, must be provided in the separate :ref:`CPP` file as input. -We have base example classes that the user can take and modify to whatever your need is. Within the Sorcha :ref:`configs`, the user would then specify when class would use and provide the required :ref:`CPP` file on the command line. We also have 2 pre-made example classes that can augment the calculated apparent magnitude of each synthetic object, One for handling cometary activity as a function of heliocentric distance and one that applies rotational light curves to the synthetic objects. In both cases, any derived class must inherit from the correspondig base class and follow its API, to ensure that sorcha knows how to find and use your class. +We have base example classes that the user can take and modify to whatever your need is. Within the Sorcha :ref:`configs`, the user would then specify when class would use and provide the required :ref:`CPP` file on the command line. We also have 2 pre-made example classes that can augment the calculated apparent magnitude of each synthetic object, One for handling cometary activity as a function of heliocentric distance and one that applies rotational light curves to the synthetic objects. In both cases, any derived class must inherit from the corresponding base class and follow its API, to ensure that sorcha knows how to find and use your class. Cometary Activity or Simulating Other Active Objects -------------------------------------------------------- @@ -14,7 +14,7 @@ Cometary Activity or Simulating Other Active Objects Rotational Light Curve Effects ----------------------------------- -The base lightcurve class is `AbstractLightCurve `_ (see below). Inside the `sorcha addons github repository `_, we provide a simple example implementation where the apparent magnitude of the object (that is, the magnitude after all geometric effects have been taken into account), has a sinusoidal term added to it. To use this function, in the :ref:`CPP` file, the user must provide a light curve amplitude (`LCA`), corresponding to half the peak-to-peak amplitude for the magnitude changes, a period `Period`, and a reference time `Time0` where the light curve is at 0 - if these are not provided, the software will produce an error message. Despite being simple, that implementation shows all the class methods that need to be implemented for a custom light curve function. +The base lightcurve class is `AbstractLightCurve `_ (see below). Inside the `sorcha addons GitHub repository `_, we provide a simple example implementation where the apparent magnitude of the object (that is, the magnitude after all geometric effects have been taken into account), has a sinusoidal term added to it. To use this function, in the :ref:`CPP` file, the user must provide a light curve amplitude (`LCA`), corresponding to half the peak-to-peak amplitude for the magnitude changes, a period `Period`, and a reference time `Time0` where the light curve is at 0 - if these are not provided, the software will produce an error message. Despite being simple, that implementation shows all the class methods that need to be implemented for a custom light curve function. .. literalinclude:: ../src/sorcha/lightcurves/base_lightcurve.py :language: python diff --git a/docs/ephemerisgen.rst b/docs/ephemerisgen.rst index b34cb5a7..aa9d992e 100644 --- a/docs/ephemerisgen.rst +++ b/docs/ephemerisgen.rst @@ -12,7 +12,7 @@ Sorcha's ephemeris generator is powered by `ASSIST `_ 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 ascenion, 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) `_ 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. Because ASSIST uses REBOUND's `IAS15 integrator `_, 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 `_ ephemeris, provided by NASA's `Navigation and Ancillary Information Facility (NAIF) `_. 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. @@ -46,7 +46,7 @@ Here's the list of asteroid pertubers that are included in the ASSIST+REBOUND in - **(4) Vesta = A807 FA** .. warning:: - If you simulate the orbits of these select asteroids you will get **POOR results** with the internal Sorcha epehmeris 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. + 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. Tuning the Ephemeris Generator ----------------------------------- @@ -62,10 +62,10 @@ There are several tunable options for the ephemeris generation which are describ .. 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. -Auxillary Files +Auxiliary Files ----------------- -A number of auxillary file available from the `Minor Planet Center `_ and `NASA's Navigation and Ancillary Information Facility (NAIF) `_ are required for ephemeris generation: +A number of auxiliary file available from the `Minor Planet Center `_ and `NASA's Navigation and Ancillary Information Facility (NAIF) `_ are required for ephemeris generation: - **naif0012.tls** is the leap second file. This changes whenever there is a new leap second. The last was in 2017. - **earth_720101_070426.bpc** is the historical Earth orientation specification. This should not change, unless there is a new model. @@ -76,5 +76,5 @@ A number of auxillary file available from the `Minor Planet Center `__. The contents of the file is below: +Next, we need to produce the :ref:`physical`, which we call 'sspp_testset_colours.txt'. This file assigns colors, phase curve properties, and absolute magnitudes to each of the simulated small bodies whose orbits are defined in our input orbit file. You can download the file from `here `__. The contents of the file is below: .. literalinclude:: ../demo/sspp_testset_colours.txt :language: text .. note:: - For this tutorial, we have defined chosen the main filter to be r-band. In the following configuration file, we wil list the r filter first when we have to input ourlist of filters to use. + For this tutorial, we have defined chosen the main filter to be r-band. In the following configuration file, we will list the r filter first when we have to input our list of filters to use. Getting the Pointing Database ------------------------------------------ @@ -45,7 +45,7 @@ For this tutorial, we're using the first year of the baseline v2.0 LSST cadence Setting Up Sorcha's Configuration File ------------------------------------------ -The key information about the simulation paramteres are held in the configuration file. For further details check out our :ref:`configs` page. We'll be using the configuration file we have set up to get you started. You can download the file from `here `__. The contents of the file is below: +The key information about the simulation parameters are held in the configuration file. For further details check out our :ref:`configs` page. We'll be using the configuration file we have set up to get you started. You can download the file from `here `__. The contents of the file is below: .. literalinclude:: ../demo/sorcha_config_demo.ini :language: text @@ -54,13 +54,13 @@ The key information about the simulation paramteres are held in the configuratio For this tutorial, we have set up Sorcha to only find detections on g,r,i,z,u, or y filter observations, by what we have set the **observing_filters** parameter to. Since we specified the absolute magnitude and colors for our synthetic objects to r-band, the r filter starts the list of filters for **observing_filters**. .. note:: - This config file sdets the output to be in CSV format. + This config file sets the output to be in CSV format. Running Sorcha ---------------------- -We now have all the required input files. If you downloaded the Sorcha repository, start by moving into the sorcha directory or make a demo directory called **demo** and move/copy all the input files into there. For this example run, we assume that you have downloaded the required ephemeris generator's auxiliary files to ./ar_files. Check the :ref:`installation` instuctions for further details. +We now have all the required input files. If you downloaded the Sorcha repository, start by moving into the sorcha directory or make a demo directory called **demo** and move/copy all the input files into there. For this example run, we assume that you have downloaded the required ephemeris generator's auxiliary files to ./ar_files. Check the :ref:`installation` instructions for further details. Next, let's take a look at the command line arguments for sorcha. On the command line, typing:: @@ -90,7 +90,7 @@ The output will appear in a csv file (testrun_e2e.csv) in your current directory If you want to run this command a second time you'll need to add a **-f** flag to the command line to force overwriting output files that already were exist in the output directory. Do note that the previous run's log and error log files will not be removed. New log files are generated at each run. .. warning:: - Only one instance of Sorcha should be run per output directory to ensure that distict log and error files are created for each Sorcha run. Make sure to have different output pathways if you are running multiple instances on the same compute node. + Only one instance of Sorcha should be run per output directory to ensure that distinct log and error files are created for each Sorcha run. Make sure to have different output pathways if you are running multiple instances on the same compute node. .. note:: - This test run is using pre-generated ephemeris already stored in the demo directory of the Sorcha github repository. + This test run is using pre-generated ephemeris already stored in the demo directory of the Sorcha GitHub repository. diff --git a/docs/index.rst b/docs/index.rst index 818b0bbc..24d6c2c1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,13 +18,13 @@ or brightness in Irish and Scots Gaelic, and our software is estimating the brig simulated Solar System small bodies and determines which ones the survey could detect in each of the survey's observations or based on user set criteria. Sorcha has been designed with the `Vera C. Rubin Observatory Legacy Survey of Space and Time (LSST) `_ -in mind. The software has a modulardesign, and with some effort it can be adapted to be +in mind. The software has a modular design, and with some effort it can be adapted to be used with any survey. .. warning:: This documentation site and the software package it describes are under active development. Validation is still on-going. DO NOT USE this for science - purposes just yet. WE REALLY MEAN THIS. THE CODEBASE IS UNDER HEAVY DEVLEOPMENT. + purposes just yet. WE REALLY MEAN THIS. THE CODEBASE IS UNDER HEAVY DEVELOPMENT. Welcome to Sorcha's documentation! diff --git a/docs/inputs.rst b/docs/inputs.rst index 6f103c7d..b1821e08 100644 --- a/docs/inputs.rst +++ b/docs/inputs.rst @@ -4,11 +4,11 @@ Inputs ========== .. note:: - The user must specify the properties of each synthetic planetesimal individually: an orbit, other physical parameters (like color, asbolute magnitude, phase curve parameters, etc), and, optionally if needed, complex physical parameters and the computer ephemeris. + The user must specify the properties of each synthetic planetesimal individually: an orbit, other physical parameters (like color, absolute magnitude, phase curve parameters, etc), and, optionally if needed, complex physical parameters and the computer ephemeris. There is a set of input files that are required to run the Sorcha codes, which describe the orbital -and physical parameters for synthetic planetesimals that are being simulated. These files are: an orbit file, a physical paramerer file,the LSST pointing database, and optionally, an ephemeris file with positions of where the simulated particles are located within some distance of the survey field poitings, and a complex parameter file for more advanced handling of rotational light curves and other brigthness enhacements (such as due to cometary activity) . Each of these files are described within this section and example files are shown. +and physical parameters for synthetic planetesimals that are being simulated. These files are: an orbit file, a physical parameter file,the LSST pointing database, and optionally, an ephemeris file with positions of where the simulated particles are located within some distance of the survey field poitings, and a complex parameter file for more advanced handling of rotational light curves and other brightness enhancements (such as due to cometary activity) . Each of these files are described within this section and example files are shown. .. image:: images/survey_simulator_flow_chart.png @@ -16,10 +16,10 @@ and physical parameters for synthetic planetesimals that are being simulated. Th :alt: An overview of the inputs and outputs of the Sorcha code. .. tip:: - Each synthetic planetesimal has its own unique object identifier set by the user and must have entries in the orbits and physical parameters files, as well as the cometary activity file, if used. + Each synthetic planetesimal has its own unique object identifier set by the user and must have entries in the orbits and physical parameters files, as well as the cometary activity file, if used. .. warning:: - Sorcha is not checking whether or not a planetesimal ID has been repeated in another row of the input files. **It is up to the user to ensure their input files include only unique IDs**. + Sorcha is not checking whether or not a planetesimal ID has been repeated in another row of the input files. **It is up to the user to ensure their input files include only unique IDs**. .. _orbits: @@ -33,10 +33,10 @@ This is a file which contains the orbital information of a set of synthetic obje * The orbit file **must** have a consistent format (i.e. Cometary or Keplerian or Cartesian) throughout * The ordering of the columns does not matter as long as the required columns exist and have entries * The first row in the orbit file **must** be a header listing the columns names - * The **correct capitalization of column names** is required + * The **correct capitalization of column names** is required * The orbit file can be either **white space separated** or **comma value separated (CSV)** - * Each simulated particle **must** have a unique string identifier - * The orbit file **must only** have 9 columns (object identifier, format column, 6 orbital parameters, and a time epoch) + * Each simulated particle **must** have a unique string identifier + * The orbit file **must only** have 9 columns (object identifier, format column, 6 orbital parameters, and a time epoch) .. warning:: Sorcha assumes **heliocentric** orbits are provided as input! @@ -121,7 +121,7 @@ An example of an orbit file in Keplarian format:: Cartesian Orbit Format ~~~~~~~~~~~~~~~~~~~~~~~ -An example of an orbit file, in Keplarian format, with the object ID represented by a unique set of numbers:: +An example of an orbit file, in Keplerian format, with the object ID represented by a unique set of numbers:: ObjID,FORMAT,x,y,z,xdot,ydot,zdot,epochMJD_TDB STC001TFa,CART,36.701800449281706,-8.770729364470023,-0.6261488665458296,0.0007155581026554,0.0026593939322716,7.344098975957749e-06,54466.0,36.54594860110992,0.04317 @@ -164,7 +164,7 @@ An example of an orbit file, in Keplarian format, with the object ID represented Physical Parameters File ------------------------------------------- -The input file for the physical parameters includes information about the objects optical colors, phase curve parameters, and absolute magnitude. The contents of this file are the bare minimum needed to simulate survey detections. For more advanced handling of the apparent magntiude of the synthetic objects including light curve effects and cometary activity,you would also specify values in the complex physical parameters file. +The input file for the physical parameters includes information about the objects optical colors, phase curve parameters, and absolute magnitude. The contents of this file are the bare minimum needed to simulate survey detections. For more advanced handling of the apparent magnitude of the synthetic objects including light curve effects and cometary activity,you would also specify values in the complex physical parameters file. .. tip:: * The ordering of the columns does not matter as long as the required columns exist and have entries @@ -173,8 +173,8 @@ The input file for the physical parameters includes information about the object * The physical parameters file can be either **white space separated** or **comma value separated (CSV)** * Each simulated object **must** have a unique string identifier * You **must use the same phase curve prescription for all simulated objects**. If you want to use different phase curve prescriptions for different synthetic populations, you will need to run them in separate input files to Sorcha - * If the phase curve function is set to NONE in the configuration value then no phase curve parameters values are required in the physical paramters files. - * In the config file you can decide which filters you want have Sorcha run on and specify which filter is the main filter that the absolute magnitude is defined for. You only need to provide colors for those fliters specified in the config file. + * If the phase curve function is set to NONE in the configuration value then no phase curve parameters values are required in the physical parameters files. + * In the config file you can decide which filters you want have Sorcha run on and specify which filter is the main filter that the absolute magnitude is defined for. You only need to provide colors for those filters specified in the config file. .. note:: For readability we show examples of white space separated files below. @@ -199,9 +199,9 @@ An example of the physical parameters file where a HG prescription is specified St500003a 6.67 1.72 0.48 -0.11 -0.12 -0.12 0.15 0.16 0.12 0.20 0.15 0.19 St500004a 10.2 1.90 0.58 -0.21 -0.30 -0.39 0.15 0.15 0.16 0.15 0.14 0.16 -Rubin Observatory will survey the sky in six broadband (optical filters), *u, g, r, i, z, and y* . In the physical parameters file, you will specify the object's absolute magnitude in the main filter (as specificed in the config file. usually this is g or r band) and then provide the synthetic planetesimal's color in other filters relative to the main filter. +Rubin Observatory will survey the sky in six broadband (optical filters), *u, g, r, i, z, and y* . In the physical parameters file, you will specify the object's absolute magnitude in the main filter (as specified in the config file. usually this is g or r band) and then provide the synthetic planetesimal's color in other filters relative to the main filter. -We have implemented several phase curve paramterizations that can be specified in the config file and the inputted through the physical parameters. **You can either specify one set of phase curve parameters for all filters or specify values for each filter examined by Sorcha.** We are using the `sbpy `_ phase function utilities. The supported options are: `HG `_, `HG1G2 `_, `HG12 `_, `linear `_ (specified by S in the header of the physical parameters file), and none (if no columnss for phase curve are included in the physical parameters file than the synthetic object is considered to have a flat phase curve). +We have implemented several phase curve paramterizations that can be specified in the config file and the inputted through the physical parameters. **You can either specify one set of phase curve parameters for all filters or specify values for each filter examined by Sorcha.** We are using the `sbpy `_ phase function utilities. The supported options are: `HG `_, `HG1G2 `_, `HG12 `_, `linear `_ (specified by S in the header of the physical parameters file), and none (if no columns for phase curve are included in the physical parameters file than the synthetic object is considered to have a flat phase curve). +------------------+----------------------------------------------------------------------------------+ | Keyword | Description | @@ -216,10 +216,10 @@ We have implemented several phase curve paramterizations that can be specified i +------------------+----------------------------------------------------------------------------------+ ** note:: - The Phase Curve Paramters(s) column will not be present if the phase curve function/calculation is set to None in the configuration file + The Phase Curve Parameters(s) column will not be present if the phase curve function/calculation is set to None in the configuration file .. note:: - In the config file you can decide which filters you want have Sorcha run on and specify which filter is the main filter that the absolute magnitude is defined for. You only need to provide colors for those fliters specified in the config file. + In the config file you can decide which filters you want have Sorcha run on and specify which filter is the main filter that the absolute magnitude is defined for. You only need to provide colors for those filters specified in the config file. .. _pointing: @@ -229,7 +229,7 @@ Survey Pointing Database .. note:: Currently Sorcha is set up to run with the LSST cadence simulations pointing databases. -This database contains information about the LSST pointing history and observing conditions. We use observation mid-point time, right ascension, declination, rotation angle of the camera, 5-sigma limiting magnitude, filter, and seeing information in Objects in Field and Sorcha to determine if a synthetic Solar System object is observable. +This database contains information about the LSST pointing history and observing conditions. We use observation mid-point time, right ascension, declination, rotation angle of the camera, 5-sigma limiting magnitude, filter, and seeing information in Objects in Field and Sorcha to determine if a synthetic Solar System object is observable. What we call the LSST pointing database (currently simulated since Rubin Observatory hasn’t started operations) is generated through the Rubin Observatory scheduler (since 2021 referred to as `rubin_sim `_ and previously known as OpSim). This software is currently under active development and is being used to run many simulated iterations of LSST scenarios showing what the cadence would look like with differing survey strategies. A description of an early version of this python software can be found in `Delgado et al.(2014) `_.The output of rubin_sim is a sqlite database containing the pointing history and associated metadata of the simulated observation history of LSST. @@ -239,7 +239,7 @@ What we call the LSST pointing database (currently simulated since Rubin Observa .. warning:: The pointing databases times are expected to be TAI (Temps Atomique International; French for International Atomic Time), -The latest version of rubin_sim cadence simulations can be found at https://s3df.slac.stanford.edu/data/rubin/sim-data/. An example rubin_sim simulation visualized on sky is shown in the plot below of the number of on-sky visits over the 10-year simulated baseline v3.2 survey (image credit: Lynne Jones): +The latest version of rubin_sim cadence simulations can be found at https://s3df.slac.stanford.edu/data/rubin/sim-data/. An example rubin_sim simulation visualized on sky is shown in the plot below of the number of on-sky visits over the 10-year simulated baseline v3.2 survey (image credit: Lynne Jones): .. image:: images/Rubin_v3.2_baseline_visits.png :width: 410 @@ -254,27 +254,27 @@ The latest version of rubin_sim cadence simulations can be found at https://s3df Complex Physical Parameters File (Optional) --------------------------------------------------- -The complex physical parameters file is only needed if you're going to include your own rotational light curve class or cometary activity class to augment the calculated apparent magnitudes. Sorcha is set up such that any values required for this such as light curve amplitude and period per simulated object are included in file, separate from then physical paramters file, that we refer to as the complex physical parameteres file. What columns are required in the complex physical parameters file depends on what the classes you are using. +The complex physical parameters file is only needed if you're going to include your own rotational light curve class or cometary activity class to augment the calculated apparent magnitudes. Sorcha is set up such that any values required for this such as light curve amplitude and period per simulated object are included in file, separate from then physical parameters file, that we refer to as the complex physical parameters file. What columns are required in the complex physical parameters file depends on what the classes you are using. .. tip:: * The ordering of the columns does not matter as long as the required columns exist and have entries * The first row in the complex physical parameters file **must** list the columns names * The **correct capitalization of column names** is required - * The complex phyiscal parameters file can be either **white space separated** or **comma value separated (CSV)** + * 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 Ephemeris File (Optional) ----------------------------------------- .. note:: - Sorcha has an :ref:`ephemeris_gen` that we recommend using by default, but as an alternative Sorcha can read in an external file contains calculated ephemeris values for each simulated object wihtin a reasonable search radius of a given survey field pointing and observation times as specified in the survey pointing database. This could be the output from a previous Sorcha run or provided from your own separate ephemeris generation method, + Sorcha has an :ref:`ephemeris_gen` that we recommend using by default, but as an alternative Sorcha can read in an external file contains calculated ephemeris values for each simulated object within a reasonable search radius of a given survey field pointing and observation times as specified in the survey pointing database. This could be the output from a previous Sorcha run or provided from your own separate ephemeris generation method, .. tip:: * The ordering of the columns does not matter as long as the required columns exist and have entries * The first row in the physical parameters file **must** list the columns names * The **correct capitalization of column names** is required - * The ephemerist file can be either **white space separated** or **comma value separated (CSV)** + * The ephemeris file can be either **white space separated** or **comma value separated (CSV)** * Each simulated object **must** have a unique string identifier .. note:: @@ -331,13 +331,13 @@ An example of an (optional) ephemeris file:: +--------------------------+----------------------------------------------------------------------------------+ | Obs-Sun(J2000z)(km) | Cartesian Z-component of the observer's heliocentric distance (km) | +--------------------------+----------------------------------------------------------------------------------+ -|Obs-Sun(J2000vx)(km/s) | Cartesian X-component of the obsever's heliocentric velocity (km/s) | +|Obs-Sun(J2000vx)(km/s) | Cartesian X-component of the observer's heliocentric velocity (km/s) | +--------------------------+----------------------------------------------------------------------------------+ |Obs-Sun(J2000vy)(km/s) | Cartesian Y-component of the observer's heliocentric velocity (km/s) | +--------------------------+----------------------------------------------------------------------------------+ | Obs-Sun(J2000vz)(km/s) |Cartesian Z-component of the observer's heliocentric velocity (km/s) | +--------------------------+----------------------------------------------------------------------------------+ -| Sun-Ast-Obs(deg) | The phase angle between the Sun,synthetic plantesimal, & observer (deg) | +| Sun-Ast-Obs(deg) | The phase angle between the Sun,synthetic planetesimal, & observer (deg) | +--------------------------+----------------------------------------------------------------------------------+ .. note:: diff --git a/docs/installation.rst b/docs/installation.rst index 848f9e7c..534b5262 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -28,7 +28,7 @@ Sorcha has the following requirements that will be automatically installed usin * tqdm .. tip:: - We also recomend installing h5py in your conda/mamba environnment to ensure that the proper HD5 libraries are installed. + We also recommend installing h5py in your conda/mamba environment to ensure that the proper HD5 libraries are installed. @@ -89,11 +89,11 @@ Installing Sorcha in Development Mode mkdir sorcha -**Step 2** Navigate to the directory you want to store the Sorcha soure code in:: +**Step 2** Navigate to the directory you want to store the Sorcha source code in:: cd sorcha -**Step 3** Download the Sorcha soure code via:: +**Step 3** Download the Sorcha source code via:: git clone https://github.com/dirac-institute/sorcha.git @@ -103,7 +103,7 @@ Installing Sorcha in Development Mode **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 auomtatically installed:: +If you just want the source code installed so edits in the source code are automatically installed:: pip install -e . @@ -126,7 +126,7 @@ To install the necessary SPICE auxiliary files for ephemeris generation (774 MB bootstrap_sorcha_data_files .. note:: - This script will download and store the auxillary files in your computer's local cache directory. + This script will download and store the auxiliary files in your computer's local cache directory. .. 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. @@ -147,4 +147,4 @@ The output will appear in a csv file (testrun_e2e.csv) in your current directory :lines: 1-51 .. note:: - This test run is using pre-generated ephemeris already stored in the demo directory of the Sorcha github repository. + This test run is using pre-generated ephemeris already stored in the demo directory of the Sorcha GitHub repository. diff --git a/docs/outputs.rst b/docs/outputs.rst index b4400d7e..bd4b9f09 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -36,7 +36,7 @@ The format of the survey simulator output looks something like:: +------------------------------------+----------------------------------------------------------------------------------+ | optFilter | Filter Observation Taken in | +------------------------------------+----------------------------------------------------------------------------------+ -| observedPSFMag | Apparent magnitude in optFilter measured by the data management piplines | +| observedPSFMag | Apparent magnitude in optFilter measured by the data management pipelines | +------------------------------------+----------------------------------------------------------------------------------+ | observedTrailedSourceMag | Apparent magnitude in optFilter adding up all of the counts in the trail | +------------------------------------+----------------------------------------------------------------------------------+ diff --git a/docs/overview.rst b/docs/overview.rst index 156ae17f..3d5717d6 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -22,15 +22,15 @@ Sorcha by default uses its own ephemeris generator to propagate the orbits and t .. warning:: - We have validated Sorcha with its internal ephemeris generator. If the user chooses to use a different emphemeris engine's calculations as input for Sorcha, the user has the responsibiilty to check the accuracy of this input. + We have validated Sorcha with its internal ephemeris generator. If the user chooses to use a different ephemeris engine's calculations as input for Sorcha, the user has the responsibility to check the accuracy of this input. Design Philosophy ---------------------- -Sorcha has been designed in a modular way. Each filter is writen as its own function, This makes it easy to add new filters in the future if required by users. We note for dealing with rotational light curve and activity effects, we have setup Sorcha such that the user can provide their own custom classes/functions and import them into Sorcha to use. Sorcha has been designed with LSST in mind, but many of the filters already developed will be applicable to other Solar System surveys. If you are interested in incorporating your survey into Sorcha do reach out. +Sorcha has been designed in a modular way. Each filter is written as its own function, This makes it easy to add new filters in the future if required by users. We note for dealing with rotational light curve and activity effects, we have setup Sorcha such that the user can provide their own custom classes/functions and import them into Sorcha to use. Sorcha has been designed with LSST in mind, but many of the filters already developed will be applicable to other Solar System surveys. If you are interested in incorporating your survey into Sorcha do reach out. .. warning:: - For a wide variety of use cases, the user should be able to use Sorcha straight out of the box. We have designed the software such that it should be straightfoward to add in additional filters or rotational light curve/activity classes. As with any open source package, **once the user has made modifications to the code, it is the responsibility of the user to confirm these changes provide an accurate result**. + For a wide variety of use cases, the user should be able to use Sorcha straight out of the box. We have designed the software such that it should be straightforward to add in additional filters or rotational light curve/activity classes. As with any open source package, **once the user has made modifications to the code, it is the responsibility of the user to confirm these changes provide an accurate result**. .. note:: diff --git a/docs/support.rst b/docs/support.rst index 4cda4527..e9673421 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -8,25 +8,25 @@ Reporting Issues, Proposing Changes, and Contributing Contributions are very welcome. If there is a feature or functionality not yet available in Sorcha, we encourage you to propose the feature or share your code with the new enhancements. -Submitting a Github Issue +Submitting a GitHub Issue --------------------------- -The best way to get in touch about a bug, suggest enhancements to Sorcha, or recommend changes to the documentation is raise an issue through the `project's github repository `_. We have a small team working on the project, so please be patient, while we get back to you. +The best way to get in touch about a bug, suggest enhancements to Sorcha, or recommend changes to the documentation is raise an issue through the `project's GitHub repository `_. We have a small team working on the project, so please be patient, while we get back to you. Contributing Code ----------------------------------- -We welcome upgrades/bug fixes to the code, This can be done by opening a pull request in the `main Sorcha github repository `_. If you have new classes that provide enhanced light curve or activity estimations, we welcome pull requests to the `Sorcha Community Utils github repository `_. +We welcome upgrades/bug fixes to the code, This can be done by opening a pull request in the `main Sorcha GitHub repository `_. If you have new classes that provide enhanced light curve or activity estimations, we welcome pull requests to the `Sorcha Community Utils GitHub repository `_. You will need to install sorcha from the source code via pip in editable mode as described in the :ref:`installation` page. .. note:: - We recommend that if you are planning to submit a pull request with enhancements to raise a `github issue in the main sorcha repository `_ first to discuss further before submitting a pull request. + We recommend that if you are planning to submit a pull request with enhancements to raise a `GitHub issue in the main sorcha repository `_ first to discuss further before submitting a pull request. Contributing to the Documentation -------------------------------------- -We are very happy to receivet feedback on the online documentation through the `project's github repository `_. Beyond pointing out typos and small changes through issues, we welcome pull requests on the `sphinx `_ documentation used here on the readthedocs. +We are very happy to receive feedback on the online documentation through the `project's GitHub repository `_. Beyond pointing out typos and small changes through issues, we welcome pull requests on the `sphinx `_ documentation used here on the readthedocs. You will need to install the development version of Sorcha from a clone of the Sorcha repository. See the our :ref:`dev_mode` instructions for further details. diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index b73d7ad5..a1bbda43 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -39,7 +39,7 @@ it might be your computer setup. SQLite uses a temporary store to hold temporary Mismatch in Inputs --------------------- There are several files associated with the synthetic small bodies which are passed into Sorcha. These are -the orbit file, the physical parameter file and an optional complexy parameters file and optional ephemeris +the orbit file, the physical parameter file and an optional complex parameters file and optional ephemeris file (if not using the ephemeris generator within sorcha. Each provide specific information about the synthetic population that is being analysed. Within these files, it is necessary to specify an entry for every object. The Sorcha code will run a check to ensure that all entries have an associated orbit and From fc01531df09712b5fc20aa92a4cf21a644db5371 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20B=C3=A1nffy?= Date: Thu, 23 Nov 2023 18:30:28 +0000 Subject: [PATCH 2/3] Whitespace fix --- docs/inputs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/inputs.rst b/docs/inputs.rst index b1821e08..c84b5b33 100644 --- a/docs/inputs.rst +++ b/docs/inputs.rst @@ -331,7 +331,7 @@ An example of an (optional) ephemeris file:: +--------------------------+----------------------------------------------------------------------------------+ | Obs-Sun(J2000z)(km) | Cartesian Z-component of the observer's heliocentric distance (km) | +--------------------------+----------------------------------------------------------------------------------+ -|Obs-Sun(J2000vx)(km/s) | Cartesian X-component of the observer's heliocentric velocity (km/s) | +|Obs-Sun(J2000vx)(km/s) | Cartesian X-component of the observer's heliocentric velocity (km/s) | +--------------------------+----------------------------------------------------------------------------------+ |Obs-Sun(J2000vy)(km/s) | Cartesian Y-component of the observer's heliocentric velocity (km/s) | +--------------------------+----------------------------------------------------------------------------------+ From b0a682242a32daa823f37bc9689c13fe85f17c14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20B=C3=A1nffy?= Date: Thu, 23 Nov 2023 18:43:05 +0000 Subject: [PATCH 3/3] s/distamce/distance/ --- docs/inputs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/inputs.rst b/docs/inputs.rst index c84b5b33..1c893673 100644 --- a/docs/inputs.rst +++ b/docs/inputs.rst @@ -313,7 +313,7 @@ An example of an (optional) ephemeris file:: +--------------------------+----------------------------------------------------------------------------------+ | AstDecRate(deg/day) | Synthetic plantesimal's declination rate of motion (deg/day) | +--------------------------+----------------------------------------------------------------------------------+ -| Ast-Sun(J2000x)(km) | Cartesian X-component of the synthetic planetesimal's heliocentric distamce (km)| +| Ast-Sun(J2000x)(km) | Cartesian X-component of the synthetic planetesimal's heliocentric distance (km)| +--------------------------+----------------------------------------------------------------------------------+ | Ast-Sun(J2000y)(km) | Cartesian Y-component of the synthetic planetesimal's heliocentric distance (km)| +--------------------------+----------------------------------------------------------------------------------+ @@ -325,7 +325,7 @@ An example of an (optional) ephemeris file:: +--------------------------+----------------------------------------------------------------------------------+ | Ast-Sun(J2000vz)(km/s) |Cartesian Z-component of the synthetic planetesimal's heliocentric velocity (km/s)| +--------------------------+----------------------------------------------------------------------------------+ -| Obs-Sun(J2000x)(km) | Cartesian X-component of observer's heliocentric distamce (km) | +| Obs-Sun(J2000x)(km) | Cartesian X-component of observer's heliocentric distance (km) | +--------------------------+----------------------------------------------------------------------------------+ | Obs-Sun(J2000y)(km) | Cartesian Y-component of the observer's heliocentric distance (km) | +--------------------------+----------------------------------------------------------------------------------+