rubin-sim 2.6.1.dev2__py3-none-any.whl

docs/installation.rst

@@ -0,0 +1,76 @@
+.. py:currentmodule:: rubin_sim
+
+.. _installation:
+
+############
+Installation
+############
+
+Quick Installation
+------------------
+
+Installation from PyPI:
+
+::
+
+    pip install rubin-sim
+    scheduler_download_data 
+    rs_download_data
+
+Note: pip installation of rubin-sim will lack the JPL data (DE405, etc.)
+that is needed to actually run ``pyoorb``, used in ``rubin_sim.moving_objects``, as this is not currently available from PyPI.
+Please see the `oorb installation instructions <https://github.com/oorb/oorb/wiki/Installation>`_ for more information.
+
+or from conda-forge:
+
+::
+
+    conda install -c conda-forge rubin-sim
+    scheduler_download_data 
+    rs_download_data
+
+The `scheduler_download_data` and `rs_download_data` commands will
+download data files to the default location of `~/rubin_sim_data`.
+To store the data elsewhere, see instructions at
+:ref:`Data Download<data-download>`.
+
+For Developer Use
+-----------------
+
+First, clone the `rubin_sim <https://github.com/lsst/rubin_sim>`_ repository:
+
+::
+
+ git clone git@github.com:lsst/rubin_sim.git
+ cd rubin_sim
+ conda create --channel conda-forge --name rubin-sim --file requirements.txt python=3.12
+ conda activate rubin-sim
+ conda install -c conda-forge --file=test-requirements.txt # Optional test requirements
+ pip install -e . --no-deps
+ scheduler_download_data 
+ rs_download_data
+
+The `scheduler_download_data` and `rs_download_data` commands will
+download data files to the default location of `~/rubin_sim_data`.
+To store the data elsewhere, see instructions at
+:ref:`Data Download<data-download>`.
+
+Note conda may override previous installs of 
+`rubin_scheduler`, in which case one can uninstall the conda version
+and re-run `pip install -e . --no-deps` from the needed git repo directory.
+
+Building Documentation
+----------------------
+
+An online copy of the documentation is available at https://rubin-sim.lsst.io,
+however building a local copy can be done as follows:
+
+::
+
+ pip install "documenteer[guide]"
+ cd docs
+ make html
+
+
+The root of the local documentation will then be ``docs/_build/html/index.html``.
+

docs/introduction.rst

@@ -0,0 +1,37 @@
+.. py:currentmodule:: rubin_sim
+
+.. _introduction:
+
+############
+Introduction
+############
+
+The `Legacy Survey of Space and Time <http://www.lsst.org>`_ (LSST)
+is anticipated to encompass around 2 million observations spanning a decade,
+averaging 800 visits per night. The ``rubin_sim`` package was built to help
+understand the predicted performance of the LSST.
+
+The :ref:`Phot Utils<phot-utils>` module provides synthetic photometry
+using provided throughput curves based on current predicted performance.
+
+The :ref:`skybrightness<skybrightness>` module incorporates the ESO
+sky model, modified to match measured sky conditions at the LSST site,
+including an addition of a model for twilight skybrightness. This is used
+to generate the pre-calculated skybrightness data used in
+`rubin_scheduler <rubin-scheduler.lsst.io/skybrightness-pre.html>`_.
+
+The :ref:`Moving Objects<moving-objects>` module provides a way to create
+synthetic observations of moving objects, based on how they would appear in
+pointing databases ("opsims") created by
+`rubin_scheduler <rubin-scheduler.lsst.io>`_.
+
+One of the major goals for ``rubin_sim`` is to enable efficient and
+scientifically varied evaluation of the LSST survey strategy and progress,
+by providing a framework to enable these metrics to run in a
+standardized way on opsim outputs.
+The :ref:`Metrics Analysis Framework<maf>` module provides these tools.
+
+.. toctree::
+    :maxdepth: 2
+
+    User Guide <user-guide>

docs/maf-api-batches.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-batches:
+
+=======
+Batches
+=======
+
+.. automodule:: rubin_sim.maf.batches
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-db.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-db:
+
+==============
+Databases (db)
+==============
+
+.. automodule:: rubin_sim.maf.db
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-maf-contrib.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-maf-contrib:
+
+===========
+Maf Contrib
+===========
+
+.. automodule:: rubin_sim.maf.maf_contrib
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-maps.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-maps:
+
+=======
+Maps
+=======
+
+.. automodule:: rubin_sim.maf.maps
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-metricbundles.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-metricbundles:
+
+==============
+Metric Bundles
+==============
+
+.. automodule:: rubin_sim.maf.metric_bundles
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-metrics.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-metrics:
+
+=======
+Metrics
+=======
+
+.. automodule:: rubin_sim.maf.metrics
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-plots.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-plots:
+
+=======
+Plots
+=======
+
+.. automodule:: rubin_sim.maf.plots
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-run-comparison.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-run-comparison:
+
+==============
+Run Comparison
+==============
+
+.. automodule:: rubin_sim.maf.run_comparison
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-slicers.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-slicers:
+
+=======
+Slicers
+=======
+
+.. automodule:: rubin_sim.maf.slicers
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-stackers.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-stackers:
+
+========
+Stackers
+========
+
+.. automodule:: rubin_sim.maf.stackers
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api-utils.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api-utils:
+
+=======
+Utils
+=======
+
+.. automodule:: rubin_sim.maf.utils
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/maf-api.rst

@@ -0,0 +1,22 @@
+.. py:currentmodule:: rubin_sim.maf
+
+.. _maf-api:
+
+=======
+MAF API
+=======
+
+
+.. toctree::
+
+    Batches <maf-api-batches>
+    Databases (db) <maf-api-db>
+    Maps <maf-api-maps>
+    Maf Contrib <maf-api-maf-contrib>
+    Metrics <maf-api-metrics>
+    MetricBundles <maf-api-metricbundles>
+    Plots <maf-api-plots>
+    Run Comparison <maf-api-run-comparison>
+    Slicers <maf-api-slicers>
+    Stackers <maf-api-stackers>
+    Utils <maf-api-utils>

docs/maf.rst

@@ -0,0 +1,60 @@
+.. py:currentmodule:: rubin_sim
+
+.. _maf:
+
+################################
+Metrics Analysis Framework (MAF)
+################################
+
+The ``rubin_sim.maf`` Metrics Analysis Framework (MAF) module is
+intended to make it easier to write code to analyze our simulated LSST
+pointing histories (often called "opsim outputs").
+
+As an example: suppose one wanted to evaluate the LSST's performance in
+regards to
+characterizing a particular kind of periodic variable in a given simulated
+survey. As such, you might have particular requirements on the parameters
+of the observations at each point in RA/Dec space -- MAF will handle getting
+the pointing history from the OpSim output database, splitting them up into
+the observations relevant for each RA/Dec point, feeding these observations
+into your contributed piece of code, and then consolidating the results of
+that evaluation from each RA/Dec location into a map over the entire sky and
+presenting those results in a variety of formats (a sky map visualization,
+an area-weighted histogram, a power spectrum, or -- with a small bit of additional
+analysis -- statistical summaries over the observed sky, such as the mean,
+median, RMS, minimum or maximum values). In this case, you would only have
+to write a small piece of code (a *metric*) that makes the actual evaluation,
+assuming you have the relevant observations for a single piece of sky.
+A simple list of all :ref:`available metrics <maf-metric-list>` is available.
+
+A concrete example of this can be found in the KNeMetric - which is illustrated
+in depth in a notebook in the github repo at `lsst/rubin_sim_notebooks
+<https://github.com/lsst/rubin_sim_notebooks/blob/main/maf/science/KNe%20Metric.ipynb>`_
+(see the maf/science directory).
+
+MAF also provides lots of ready to use :ref:`metrics <maf-metric-list>`, as well as
+a variety of ways to subdivide the pointing histories using :py:obj:`rubin_sim.maf.slicers`
+-- a typical use case is to evaluate a quantity at all points over the sky, which would use
+the :py:class:`rubin_sim.maf.slicers.HealpixSlicer` slicer, but there are
+other spatially based slicers, such as the
+:py:class:`rubin_sim.maf.slicers.UserPointsSlicer` which lets a user define
+specific points at which to evaluate a given metric. Some metrics should be
+evaluated on a basis which depends on a single data value, rather than spatially
+across the sky (such as evaluating the time between filter changes per night, or
+counting the number of observations per airmass bin) -- these typically need a
+:py:class:`rubin_sim.maf.slicers.OneDSlicer`. Finally, there are metrics should
+be applied to all of the observations at once, rather than subdividing them on
+any basis; these should use the :py:class:`rubin_sim.maf.slicers.UniSlicer`.
+Each slicer pairs with different plotting functions automatically, although
+this is user-adjustable. MAF provides the framework to combine metrics, slicers
+these plotting functions, and methods to save and restore the results of
+each metric calculation.
+
+For more examples of using MAF, please see our `tutorials`_.
+
+.. _tutorials: https://github.com/lsst/rubin_sim_notebooks/tree/main/maf
+
+
+.. toctree::
+
+    List of Available Metrics <maf-metric-list>

docs/metric_list.py

@@ -0,0 +1,49 @@
+__all__ = ("make_metric_list",)
+
+import inspect
+
+import rubin_sim.maf.maf_contrib as maf_contrib
+import rubin_sim.maf.metrics as metrics
+
+
+def make_metric_list(outfile):
+    f = open(outfile, "w")
+
+    # Print header
+    print(".. py:currentmodule:: rubin_sim.maf", file=f)
+    print("", file=f)
+    print(".. _maf-metric-list:", file=f)
+    print("", file=f)
+    print("################################", file=f)
+    print("rubin_sim MAF: Available metrics", file=f)
+    print("################################", file=f)
+
+    print(" ", file=f)
+
+    print("Core LSST MAF metrics", file=f)
+    print("^^^^^^^^^^^^^^^^^^^^^", file=f)
+    print(" ", file=f)
+    for name, obj in inspect.getmembers(metrics):
+        if inspect.isclass(obj):
+            modname = inspect.getmodule(obj).__name__
+            if modname.startswith("rubin_sim.maf.metrics"):
+                link = f":py:class:`~rubin_sim.maf.metrics.{name}` "
+                simpledoc = inspect.getdoc(obj).split("\n")[0]
+                print(f"- {link} \n \t {simpledoc}", file=f)
+    print(" ", file=f)
+
+    print("Contributed maf_contrib metrics", file=f)
+    print("^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^", file=f)
+    print(" ", file=f)
+    for name, obj in inspect.getmembers(maf_contrib):
+        if inspect.isclass(obj):
+            modname = inspect.getmodule(obj).__name__
+            if modname.startswith("rubin_sim.maf.maf_contrib") and name.endswith("Metric"):
+                link = f":py:class:`~rubin_sim.maf.maf_contrib.{name}` "
+                simpledoc = inspect.getdoc(obj).split("\n")[0]
+                print(f"- {link} \n \t {simpledoc}", file=f)
+    print(" ", file=f)
+
+
+if __name__ == "__main__":
+    make_metric_list("maf-metric-list.rst")

docs/moving-objects-api.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.moving_objects
+
+.. _moving-objects-api:
+
+==================
+Moving Objects API
+==================
+
+.. automodule:: rubin_sim.moving_objects
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/moving-objects.rst

@@ -0,0 +1,22 @@
+.. py:currentmodule:: rubin_sim
+
+.. _moving-objects:
+
+
+##############
+Moving Objects
+##############
+
+The ``rubin_sim.movingObjects`` module provides tools to
+generate simulated ephemerides of a population of
+small bodies throughout an LSST pointing history.
+These ephemerides are typically used for further
+analysis in :ref:`MAF <maf>` to evaluate the effect of
+survey strategy on various populations
+of Solar System objects.
+
+There are several populations available in the "orbits" directory of
+$RUBIN_SIM_DATA_DIR. Many of these populations were contributed or
+enhanced by the LSST Solar System Science Collaboration (SSSC).
+Further documentation on these orbital populations is available in the
+`LSST-SSSC "SSSC_test_populations" <https://github.com/lsst-sssc/SSSC_test_populations_gitlfs/tree/master/MAF_TEST>`_ repo.

docs/phot-utils-api.rst

@@ -0,0 +1,12 @@
+.. py:currentmodule:: rubin_sim.phot_utils
+
+.. _phot-utils-api:
+
+==============
+Phot Utils API
+==============
+
+.. automodule:: rubin_sim.phot_utils
+    :imported-members:
+    :members:
+    :show-inheritance:

docs/phot-utils.rst

@@ -0,0 +1,11 @@
+.. py:currentmodule:: rubin_sim
+
+.. _phot-utils:
+
+##########
+Phot Utils
+##########
+
+The ``rubin_sim.photUtils`` module provides synthetic photometry
+and SNR calculation methods for Rubin. There are expected throughput
+curves available in the 'throughputs' directory of $RUBIN_SIM_DATA_DIR.

docs/prenight.rst

@@ -0,0 +1,117 @@
+.. py:currentmodule:: rubin_sim.data
+
+.. _prenight:
+
+============================================================
+Running pre-night simulations and adding them to the archive
+============================================================
+
+Introduction
+============
+
+Prenight simulation tools generate simulations of a few nights of observing, and add them to an archive.
+These simulations can then be seen by `schedview`'s reporting tools, and used to generate pre-night brifing reports.
+Normally, these simulation are run by submitting the `batch/run_prenight_sims.sh` script as a batch job, either by hand or using a cron job.
+For more fine-grained control, the simulations and be run and added to the archive using lower-level tools,
+
+Running a standard set of pre-night simulations
+===============================================
+
+The standard set of pre-night simulatios can be run by calling the `batch/run_prenight_sims.sh` shell (for SV) or `batch/run_auxtel_prenight_sims.sh` (for auxtel) scripts.
+
+If `RUBIN_SIM_DIR` is the `rubin_sim` root director, it can be called thus::
+
+    ${RUBIN_SIM_DIR}/batch/run_prenight_sims.sh
+
+or thus::
+
+    ${RUBIN_SIM_DIR}/batch/run_auxtel_prenight_sims.sh auxtel
+
+or they can be submitted as a batch job to slurm.
+At the USDF, there is an installation of `rubin_sim` at `/sdf/data/rubin/shared/scheduler/packages/rubin_sim` such that the commands become::
+
+    /sdf/data/rubin/shared/scheduler/packages/rubin_sim/batch/run_auxtel_prenight_sims.sh
+    sdf/data/rubin/shared/scheduler/packages/rubin_sim/batch/run_prenight_sims.sh
+
+
+These batch jobs will record their output in:
+
+* `/sdf/data/rubin/shared/scheduler/prenight/sbatch/run_prenight_sims_%A_%a.out` and
+* `/sdf/data/rubin/shared/scheduler/prenight/sbatch/run_prenight_sims_%A_%a.err`
+
+The working files can be found in `/sdf/data/rubin/shared/scheduler/prenight/work/run_prenight_sims/%Y-%m-%dT%H%M%`.
+
+Automated runs of prenight simulations
+======================================
+
+Batch jobs are submitted automatically each morning following the `sbatch` commands shown above.
+The `crontab` entries are::
+
+    15 6 * * * /opt/slurm/slurm-curr/bin/sbatch /sdf/data/rubin/shared/scheduler/packages/rubin_sim/batch/run_auxtel_prenight_sims.sh 2>&1 >> /sdf/data/rubin/shared/scheduler/prenight/daily/daily_auxtel_cron.out
+    30 6 * * * /opt/slurm/slurm-curr/bin/sbatch /sdf/data/rubin/shared/scheduler/packages/rubin_sim/batch/run_prenight_sims.sh 2>&1 >> /sdf/data/rubin/shared/scheduler/prenight/daily/daily_simonyi_cron.out
+
+
+Custom runs of prenight simulations
+===================================
+
+Much of the `run_prenight_sims.sh` script is dedicated to figuring out what environment to use and configuring it.
+If these defaults are not desired, a user can configure an environment to their liking, and run the simulation with the following steps.
+This environment must have the following installed:
+
+* `rubin_scheduler` (`github.com/lsst/rubin_sim`)
+* `schedview`  (`github.com/lsst/schedview`)
+* `ts_fbs_utils` (`github.com/lsst-ts/ts_fbs_utils.git`)
+* `sims_sv_survey` (`github.com/lsst-sims/sims_sv_survey`)
+* `rubin_nights` (`github.com/lsst-sims/rubin_night`)
+* `lsst_resources` (`github.com/lsst/resources`)
+
+First, retrieve the set of completed visits at the start of the nights to be simulated.
+For example::
+
+    DAYOBS="20250819"
+    COMPLETED_OPSIM_DB="completed_visits.db"
+    TOKEN_FILE="~/.usdf_access_token"
+    fetch_sv_visits ${DAYOBS} ${COMPLETED_OPSIM_DB} ${TOKEN_FILE}
+
+Second, create a pickle of the scheduler you want to run::
+
+    SCHEDULER_CONFIG_SCRIPT="ts_config_ocs/Scheduler/feature_scheduler/maintel/fbs_config_sv_survey.py"
+    SCHEDULER_PICKLE="scheduler.p"
+    COMPLETED_OPSIM_DB="completed_visits.db"
+    make_sv_scheduler ${SCHEDULER_PICKLE} --opsim ${COMPLETED_OPSIM_DB} --config-script ${SCHEDULER_CONFIG_SCRIPT}
+
+Third, create a model observatory pickle::
+
+    make_model_observatory observatory.p
+
+Fourch, create an band scheduler pickle::
+
+    make_band_scheduler band_scheduler.p
+
+Finally, run the sim (and add it to the archive)::
+
+    OPSIMRUN="prenight_nominal_$(date --iso=s)"
+    LABEL="Nominal start and overhead, ideal conditions, run at $(date --iso=s)"
+    NUM_NIGHTS=3
+    ARCHIVE="s3://rubin:rubin-scheduler-prenight/opsim/"
+    DELAY=0
+    ANOM_SCALE=0
+    ANOM_SEED=1
+    run_sv_sim \
+        ${SCHEDULER_PICKLE} \
+        observatory.p \
+        "" \
+        ${DAYOBS} \
+        ${NUM_NIGHTS} \
+        ${OPSIMRUN} \
+        --keep-rewards \
+        --no-downtime \
+        --label ${LABEL} \
+        --archive ${ARCHIVE} \
+        --capture-env \
+        --delay ${DELAY} \
+        --anom-overhead-scale ${ANOM_SCALE} \
+        --anom-overhead-seed ${ANOM_SEED} \
+        --tags mytag1 mytag2 mytag3
+
+See the output of `run_sv_sim --help` for the meanings of the options.