sim_archive API#

class rubin_sim.sim_archive.AnomalousOverheadFunc(seed, slew_scale=0.0, visit_scale=0.0, slew_loc=0.0, visit_loc=0.0, min_overhead=0.0, scatter_distribution=None, scatter_kwargs=None)[source]#

Bases: object

Callable to return random overhead.

Parameters:
  • seed (int) – Random number seed.

  • slew_scale (float) – The scale for the scatter in the slew offest (seconds). Defaults to 0.0.

  • visit_scale (float, optional) – The paramater no longer does anything, and will be removed in future versions. Defaults to 0.0.

  • slew_loc (float, optional) – The location of the scatter in the slew offest (seconds). It is unlikely that this should ever be non-zero. Defaults to 0.0.

  • visit_loc (float, optional) – The paramater no longer does anything, and will be removed in future versions. Defaults to 0.0.

  • scatter_distribution (str or None, optional) – The distribution from which the scatter should be taken. This must be the name of a method of numpy.random.Generator. If None, the distribution is taken from DEFAULT_OVERHEAD_SCATTER_DIST. Defaults to None.

  • scatter_kwargs (dict or None, optional) – Dictionary of arguments passed to scatter_distribution. If None, the argumentns taken from DEFAULT_OVERHEAD_SCATTER_KWARGS.

  • min_overhead (float, optional) – The minimum possible overhead

Notes

  • The slew_scale and slew_loc parameters introduce an offset proportional to the slew time following a normal distribution. A non-zero slew_loc will sysetmatically move the center of the distribution.

  • The visit_scale and visit_loc parameters are no longer functional, and persist only to support backward compatibility.

  • The scatter_distribution and scatter_kwargs introduce an offset independent of the modeled slew and visit times, and support any distribution offered by numpy.random.Generator.

__call__(obs=None)[source]#

Return a randomized offset for the visit overhead.

Parameters:

obs (Mapping[str, Any]) – Observation record.

Returns:

offset – The offset (in seconds) between the modeled overhead between exposures and the overhead to be applied. “Overhead” is the difference in start times between succesive expusures, minus the exposure times: overhead = exp_start_2 - exp_start_1 - exptime_1. So, the offset here is time to be added to the modeled start of an exposure.

Return type:

float

default_overhead_scatter_dist: ContinuousDistribution = <scipy.stats._continuous_distns.halfnorm_gen object>#
exception rubin_sim.sim_archive.NoMatchingSimulationsFoundError[source]#

Bases: Exception

Raised when no simulations match requested criteria.

class rubin_sim.sim_archive.VisitSequenceArchiveMetadata(metadata_db_kwargs=None, metadata_db_schema=None)[source]#

Bases: object

Interface to metadata database that tracks sequences of visits.

Parameters:
  • metadata_db_kwargs (Mapping or None) – A dictionary or other mapping defining the connection parameters for connecting to the postgresql database that holds the sequence metadata. Keys are passed as keyword arguments to psycopg2.pool.SimpleConnectionPool. If None, the dictionary is built from the environment variables VSARCHIVE_PGDATABASE, VSARCHIVE_PGHOST, VSARCHIVE_PGUSER, and VSARCHIVE_PGPORT (if they exist) or corresponding module variables in rubin_sim.sim_archive.vseqarchiv (if they do not).

  • metadata_db_schema (str or None) – The schema in the database holding the metadata. If None, defaults to rubin_sim.sim_archive.vseqarchive.VSARCHIVE_PGSCHEMA. Default is None.

Notes

The visit sequence archive consists of two primary architectural components: an archive in which files associated with a sequence of visits are stored (including, optionally, the table of visits themselves); and postegresql database with tables with metadata about the sequneces of visits, including the provenance of the visits, the locations of the files associated with each sequence of visits, comments and tags associated with each sequence of visits, and basic statistics of the visits. This class is an interface to the postgresql metadata database.

comment(visitseq_uuid, comment, author=None)[source]#

Attach a comment to a visit sequence in the metadata database..

Parameters:
  • visitseq_uuid (uuid.UUID) – The UUID of the visit sequence to comment on.

  • comment (str) – The comment to attach.

  • author (str, optional) – The author of the comment. Defaults to None.

Return type:

None

conda_env_is_saved(conda_env_hash)[source]#

Check whether a conda environment with the given hash is already stored in the database.

Parameters:

conda_env_hash (bytes) – The SHA‑256 digest of the conda environment JSON representation. This value is expected to be the same output returned by compute_conda_env.

Returns:

env_exists – True if a row with the supplied hash exists in the conda_env table; False otherwise.

Return type:

bool

create_schema_in_database()[source]#

Create the visit sequence metadata schema in a database.

Return type:

None

get_comments(visitseq_uuid)[source]#

Retrieve all comments attached to a specific visit sequence.

Parameters:

visitseq_uuid (UUID) – The UUID of the visit sequence whose comments should be fetched.

Returns:

comments – A DataFrame containing the comments for the requested visit sequence. The DataFrame has the following columns:

"visitseq_uuid"

The ID of the visit sequence.

"comment_time"

Timestamp of the comment.

"author"

Name of the user who added the comment; may be None.

"comment"

The comment text.

If the visit sequence has no comments, an empty DataFrame with the above column names is returned.

Return type:

pd.DataFrame

get_file_sha256(visitseq_uuid, file_type)[source]#

Retrieve the SHA‑256 digest of a registered file.

Parameters:
  • visitseq_uuid (UUID) – The UUID of the visit sequence the file is associated with.

  • file_type (str) – Handle for the file type.

Returns:

file_sha256 – The raw SHA‑256 digest of the file contents. The value is returned as a 32‑byte object (the output of hashlib.sha256).

Return type:

bytes

get_file_url(visitseq_uuid, file_type)[source]#

Return the URL for a registered file of a given type and visit sequence UUID.

Parameters:
  • visitseq_uuid (UUID) – The UUID of the visit sequence with which the desired file is associated.

  • file_type (str) – Handle for the file type.

Returns:

url – The URL pointing to the requested file.

Return type:

str

get_sim_uuid(sim_date, daily_id)[source]#

Retrieve metadata for a visit sequence.

Parameters:
  • sim_date (date on str or int) – The creation date of the simulation to find, as a dayobs (utc-12 hour timezone)

  • daily_id (int or str) – The daily ID of the simulation to find. The daily ID is an index of simulations in the metadata added at a given sim_date: A simulation with sim_date of 2026-04-28 and daily_id of 4 is the 4th simulation added to the metadata database with a creation date of 2026-04-28. The combination sim_date and daily_id uniquely identifies a simulation in a given metadata database, but unlike UUID is not guaranteed to be unique across different metadata databases.

Returns:

uuid – The UUID corresponding to the sim_date/daily_id combination.

Return type:

UUID

get_visitseq_metadata(visitseq_uuid, table='visitseq')[source]#

Retrieve metadata for a visit sequence.

Parameters:
  • visitseq_uuid (UUID) – The UUID of the visit sequence to retrieve metadata for.

  • table (str, optional) – The table in the metadata archive database in which to search. Must be one of “visitseq”, “mixedvisitseq”, “completed”, or “simulations”. Defaults to “visitseq”.

Returns:

visitseq – A Pandas Series containing the metadata for the visit sequence.

Return type:

pd.Series

Raises:

ValueError – If the table is not one of “visitseq”, “mixedvisitseq”, “completed”, or “simulations”.

get_visitseq_url(visitseq_uuid)[source]#

Retrieve the URL for the file with the visits in a visit sequence.

Parameters:

visitseq_uuid (UUID) – The UUID of the visit sequence to search for.

Returns:

url – The URL for the visit sequence.

Return type:

str

Raises:

ValueError – If no URL is found for the visit sequence.

import_sim_from_prototype_sim_archive(archive_base, sim_date, sim_index, proto_sim_archive_uri)[source]#

Import a simulation metadata from the prototype achive.

Parameters:
  • archive_base (str) – Base location where the new archive entry will be written (e.g. an S3 bucket or a local directory). The method will write and hdf5 with visits to this location and register the resulting URL in the database.

  • sim_date (str or datetime.date) – The ISO‑formatted date (e.g. '2025-03-12') or a date object that identifies (with the sim_index) a simulation in the prototype archive.

  • sim_index (str or int) – The index of the simulation which completes the identification of the simulation in the prototype.

  • proto_sim_archive_uri (str) – Base URI of the prototype simulation archive. By default this is 's3://rubin:rubin-scheduler-prenight/opsim/'.

Returns:

visitseq_uuid – The UUID of the visit sequence that was created and registered.

Return type:

UUID

import_sim_from_yaml(metadata_yaml, archive_base=None)[source]#

Import a simulation from a YAML metadata description.

Parameters:
  • metadata_yaml (str) – YAML string with simulation metadata.

  • archive_base (str or None) – Base location of the archive to which to copy the visit sequence. If None, the visits will not be copied. Defaults to None.

Returns:

visitseq_uuid – The UUID of the newly registered visit sequence.

Return type:

UUID

insert_nightly_stats(visitseq_uuid, nightly_stats)[source]#

Instert by-night statistics into associoted with a visit sequence into the visit sequence metadata database.

Parameters:
  • visitseq_uuid (UUID) – The UUID of the visit sequence whose statistics are being recorded.

  • stats_df (pd.DataFrame) –

    A DataFrame containing the nightly statistics that were written to the database. The columns are:

    "day_obs"

    The observation day.

    "value_name"

    The value for which statistics were computed.

    "p05"

    5th percentile.

    "q1"

    25th percentile (first quartile).

    "median"

    50th percentile (median).

    "q3"

    75th percentile (third quartile).

    "p95"

    95th percentile.

    "visitseq_uuid"

    The UUID of the sequence.

    "accumulated"

    Always False for data written by this method.

  • nightly_stats (DataFrame)

Return type:

None

is_tagged(visitseq_uuid, tag)[source]#

Return whether a visit sequence is tagged with a given tag.

Parameters:
  • visitseq_uuid (UUID) – The UUID of the visit sequence.

  • tag (str) – The tag to check for.

Returns:

is_tagged – True if the visit sequence is tagged with the given tag, False otherwise.

Return type:

bool

pd_read_sql(query_template, sql_params=None, query_params=None)[source]#

Execute a SQL query using the internal PostgreSQL connection pool and return the results as a pandas DataFrame.

Parameters:
  • query_template (str) – A query template.

  • sql_params (list [sql.Composable]) – Elements that will be substituted into the template (e.g. table or schema identifiers) using psycopg2.sql.SQL.format. To make type checkers happy, you may need to explictly declare variables passed as list[sql.Composable].

  • query_params (tuple) – Positional parameters that will be bound by sqlalchemy.

Returns:

df – The result set of the query, wrapped in a DataFrame.

Return type:

pd.DataFrame

Notes

This works around limitations in pandas when dealing with complex datatypes in raw postgresql connections.

query(query, data={}, commit=False, return_result=True)[source]#

Run a simple query on the visit sequence database.

Parameters:
  • query (str or sql.SQL) – The query to send

  • data (dict) – Data to include in the query

  • commit (bool) – Commit the query (e.g. for an INSERT), defaults to False

  • return_result (bool) – Return the result, defaults to True

Returns:

result – The result of the query

Return type:

tuple

query_nightly_stats(visitseq_uuid)[source]#
Query the visit sequence metadata database for

nightly statistics.

Parameters:

visitseq_uuid (UUID) – The UUID of the visit sequence whose statistics are being recorded.

Returns:

stats_df – A table of nightly statistics.

Return type:

pd.DataFrame

record_completed_metadata(visits, label, telescope='simonyi', url=None, first_day_obs=None, last_day_obs=None, creation_time=None, query=None)[source]#

Record metadata for a sequence of visits queried from the consdb.

Parameters:
  • visits (pd.DataFrame) – A DataFrame of visits, with column names following those in consdb.

  • label (str) – A label for the sequence.

  • telescope (str) – The telescope used, either “simonyi” or “auxtel”. Defaults to “simonyi”.

  • url (str, optional) – A URL for the file from thich the table of visits can be download.

  • first_day_obs (date or int or str, optional) – The first night of observations, defined according to SITCOMTN-032 (UTC-12hrs).

  • last_day_obs (date or int or str, optional) – The last day of observations, defined according to SITCOMTN-032 (UTC-12hrs).

  • creation_time (Time, optional) – The time the sequence was created, defaults no now.

  • query (str, optional) – The query to the consdb used to get the completed visits, by default None.

Returns:

visitseq_uuid – The UUID of the new visit sequence.

Return type:

UUID

record_conda_env(conda_env_hash=None, conda_env_json=None)[source]#

Record the current Conda environment in the database.

Parameters:
  • conda_env_hash (bytes or None) – The SHA‑256 digest of the Conda environment JSON representation. None (the default) uses the current conda environment.

  • conda_env_json (str or None) – The json representing the conda environment. None (the default) uses the current conda environment.

Return type:

bytes

record_mixed_metadata(visits, label, last_early_day_obs, first_late_day_obs, early_parent_uuid, late_parent_uuid, telescope='simonyi', url=None, first_day_obs=None, last_day_obs=None, creation_time=None)[source]#

Record metadata for a new mixed visit sequence.

Parameters:
  • visits (pd.DataFrame) – A DataFrame of visits, with column names following those in consdb.

  • label (str) – A label for the sequence.

  • last_early_day_obs (date or int or str) – The last day obs of the early parent.

  • first_late_day_obs (date or int or str) – The first day obs of the late parent.

  • early_parent_uuid (UUID) – The UUID of the early parent.

  • late_parent_uuid (UUID) – The UUID of the late parent.

  • telescope (str, optional) – The telescope used, either “simonyi” or “auxtel”. Defaults to “simonyi”.

  • first_day_obs (date or int or str or None, optional) – The first night of observations, defined according to SITCOMTN-032 (UTC-12hrs).

  • last_day_obs (date or int or str or None, optional) – The last day of observations, defined according to SITCOMTN-032 (UTC-12hrs).

  • creation_time (Time or None, optional) – The time the sequence was created, defaults to now.

  • url (Optional[str], default: None)

Returns:

visitseq_uuid – The UUID of the new visit sequence.

Return type:

UUID

record_simulation_metadata(visits, label, telescope='simonyi', url=None, first_day_obs=None, last_day_obs=None, creation_time=None, scheduler_version=None, config_url=None, conda_env_sha256=None, parent_visitseq_uuid=None, sim_runner_kwargs=None, parent_last_day_obs=None)[source]#

Record metadata for a new simulation sequence.

Parameters:
  • visits (pd.DataFrame) – A DataFrame of visits, with column names following those in consdb.

  • label (str) – A label for the sequence.

  • telescope (str) – The telescope used, either “simonyi” or “auxtel”. Defaults to “simonyi”.

  • url (str, optional) – A URL for the file from thich the table of visits can be download.

  • first_day_obs (date or int or str, optional) – The first night of observations, defined according to SITCOMTN-032 (UTC-12hrs).

  • last_day_obs (date or int or str, optional) – The last day of observations, defined according to SITCOMTN-032 (UTC-12hrs).

  • creation_time (Time, optional) – The time the sequence was created, defaults to now.

  • scheduler_version (str, optional) – Version of rubin_scheduler used to run the simulation, by default None.

  • config_url (str, optional) – URL for the config script, perhaps on github, by default None.

  • conda_env_sha256 (bytes, optional) – SHA256 hash of output of conda list --json, by default None.

  • parent_visitseq_uuid (UUID, optional) – UUID of visitseq loaded into scheduler before running, by default None.

  • sim_runner_kwargs (dict, optional) – Arguments to sim_runner as a dict, by default None.

  • parent_last_day_obs (str, optional) – day_obs of last visit loaded into scheduler before running, by default None.

Returns:

visitseq_uuid – The UUID of the new visit sequence.

Return type:

UUID

record_visitseq_metadata(visits, label, telescope='simonyi', table='visitseq', url=None, first_day_obs=None, last_day_obs=None, creation_time=None)[source]#

Record metadata for a new visit sequence.

Parameters:
  • visits (pd.DataFrame) – A DataFrame of visits, with column names following those in consdb.

  • label (str) – A label for the sequence.

  • telescope (str) – The telescope used, either “simonyi” or “auxtel”. Defaults to “simonyi”.

  • table (str) – The table in the metadata archive database in which to insert the entry: one of simulations, completed, mixedvisitseq, or visitseq.

  • url (str, optional) – A URL for the file from thich the table of visits can be download.

  • first_day_obs (date or int or str, optional) – The first night of observations, defined according to SITCOMTN-032 (UTC-12hrs).

  • last_day_obs (date or int or str, optional) – The last day of observations, defined according to SITCOMTN-032 (UTC-12hrs).

  • creation_time (Time, optional) – The time the sequence was created, defaults no now.

Returns:

visitseq_uuid – The UUID of the new visit sequence.

Return type:

UUID

Notes

This method is not normally used externally, but may be occasionally needed to add non-standard sequences of visits. Standard simulations and completed sets of visits should be registered with the record_simulation_metadata and record_completed_metadata methods instead.

register_file(visitseq_uuid, file_type, file_sha256, location, update=False)[source]#

Register a file in the visit sequence metadata database.

Parameters:
  • visitseq_uuid (UUID) – The UUID of the visit sequence with which the file should be associated.

  • file_type (str) – The handle for the file type. The "visits" file type is not allowed because visit tables are recorded using set_visitseq_url.

  • file_sha256 (bytes) – The hash of the file contents.

  • location (str or lsst.resources.ResourcePath) – The location of the file to be registered.

  • update (bool, optional) – If True and a record for the same visitseq_uuid and file_type already exists, the existing row will be updated with the new SHA‑256 hash and URL. If False and a record already exists a ValueError is raised.

Raises:
  • ValueError – If file_type is "visits" (use set_visitseq_url instead), or if update is False and a record already exists for the given visitseq_uuid and file_type.

  • TypeError – If location is neither a string nor a ResourcePath.

Return type:

None

set_visitseq_url(visitseq_uuid, visitseq_url)[source]#

Update the URL for the visits file for a visit sequence.

Parameters:
  • visitseq_uuid (UUID) – The UUID of the visit sequence to update.

  • visitseq_url (str) – The new URL for the visit sequence.

Raises:

ValueError – If the table is not one of “visitseq”, “mixedvisitseq”, “completed”, or “simulations”.

Return type:

None

sim_metadata_yaml(visitseq_uuid)[source]#

Return a YAML representation of a simulation’s metadata.

Parameters:

visitseq_uuid (UUID) – The unique identifier of the visit sequence for which metadata should be exported.

Returns:

md_yaml – yaml representation of (some of) the simulation metadata in the metadata database.

Return type:

str

sims_on_night_with_stats(day_obs=None, tags=('prenight', 'ideal', 'nominal'), telescope='simonyi', max_simulation_age=2)[source]#

Return a table of simulations that cover a given night range.

Parameters:
  • day_obs (str | date | int | None, optional) – The day_obs for which to get simulations.

  • tags (tuple[str], optional) – A sequence of tags that must be present on the simulation record. The default tags are ("prenight", "ideal", "nominal"). If an empty tuple is supplied, the tag test is omitted.

  • telescope (str, optional) – The telescope simulated. The default is simonyi.

  • max_simulation_age (int, optional) – The maximum age of a simulation in days. The default is 2 days.

Returns:

vseqs – A table of metadata for matching simulations.

Return type:

pd.DataFrame

sims_on_nights(first_day_obs=None, last_day_obs=None, tags=('prenight', 'ideal', 'nominal'), telescope='simonyi', max_simulation_age=2)[source]#

Return a table of simulations that cover a given night range.

Parameters:
  • first_day_obs (str | date | int | None, optional) – The first observation day of the window for which simulations are requested. It can be specified as a datetime.date object, an ISO‑formatted string (e.g. '2025-12-01'), or an integer in SMTN‑032 format (e.g. 20251201). If None (the default), the method uses the current dayobs.

  • last_day_obs (str | date | int | None, optional) – The last observation day of the window. It accepts the same types as first_day_obs. If None the same value as first_day_obs is used, giving a single‑night query.

  • tags (tuple[str], optional) – A sequence of tags that must be present on the simulation record. The default tags are ("prenight", "ideal", "nominal"). If an empty tuple is supplied, the tag test is omitted.

  • telescope (str, optional) – The telescope simulated. The default is simonyi.

  • max_simulation_age (int, optional) – The maximum age of a simulation in days. The default is 2 days.

Returns:

vseqs – A table of metadata for matching simulations.

Return type:

pd.DataFrame

tag(visitseq_uuid, *tags)[source]#

Tag a visit sequence with one or more tags.

Parameters:
  • visitseq_uuid (UUID) – The UUID of the visit sequence.

  • *tags (str) – One or more tags to add to the visit sequence.

Return type:

None

untag(visitseq_uuid, tag)[source]#

Untag a visit sequence with a given tag.

Parameters:
  • visitseq_uuid (UUID) – The UUID of the visit sequence.

  • tag (str) – The tag to remove.

Raises:

ValueError – If the visit sequence is not tagged with the given tag.

Return type:

None

update_visitseq_metadata(visitseq_uuid, field, value)[source]#

Update a single metadata field for a visit sequence. Automatically finds the table in which to make the update.

Parameters:
  • visitseq_uuid (UUID) – The unique identifier of the visit sequence to update.

  • field (str) – The name of the column in the metadata table to modify.

  • value (object) – The new value to assign to field. The type must be compatible with the column’s database type.

Return type:

None

rubin_sim.sim_archive.add_make_scheduler_snapshot_args(parser)[source]#

Add arguments needed for saving a scheduler to an argument parser.

Parameters:

parser (ArgumentParser)

Return type:

None

rubin_sim.sim_archive.drive_sim(observatory, scheduler, label=None, tags=[], script=None, notebook=None, opsim_metadata=None, **kwargs)[source]#

Run a simulation and archive the results.

Parameters:
  • observatory (ModelObservatory) – The model for the observatory.

  • scheduler (CoreScheduler) – The scheduler to use.

  • archive_uri (str, optional) – The root URI of the archive resource into which the results should be stored. Defaults to None.

  • label (str, optional) – The label for the simulation in the archive. Defaults to None.

  • tags (list of str, optional) – The tags for the simulation in the archive. Defaults to an empty list.

  • script (str) – The filename of the script producing this simulation. Defaults to None.

  • notebook (str, optional) – The filename of the notebook producing the simulation. Defaults to None.

  • opsim_metadata (dict, optional) – Extra metadata to store in the archive.

Return type:

tuple

Returns:

  • observatory (ModelObservatory) – The model for the observatory.

  • scheduler (CoreScheduler) – The scheduler used.

  • observations (numpy.recarray) – The observations produced.

  • reward_df (pandas.DataFrame, optional) – The table of rewards. Present if record_rewards or scheduler.keep_rewards is True.

  • obs_rewards (pandas.Series, optional) – The mapping of entries in reward_df to observations. Present if record_rewards` or scheduler.keep_rewards is True.

  • resource_path (ResourcePath, optional) – The resource path to the archive of the simulation. Present if archive_uri was set.

Notes

Additional parameters not described above will be passed into sim_runner.

If the archive_uri parameter is not supplied, sim_runner is run directly, so that drive_sim can act as a drop-in replacement of sim_runner.

In a jupyter notebook, the notebook can be saved for the notebook paramater using %notebook $notebook_fname (where notebook_fname is variable holding the filename for the notebook) in the cell prior to calling drive_sim.

Parameters:

kwargs (Any)

rubin_sim.sim_archive.fetch_obsloctap_visits(day_obs=None, nights=2, telescope='simonyi', columns=('observationStartMJD', 'fieldRA', 'fieldDec', 'rotSkyPos', 'band', 'visitExposureTime', 'night', 'target_name'), max_simulation_age=None)[source]#

Return visits from latest nominal prenight briefing simulation.

Parameters:
  • day_obs (str) – The day_obs of the night, in YYYY-MM-DD format (e.g. 2025-03-26). Default None will use the date of the next sunset.

  • nights (int) – The number of nights of observations to return. Defaults to 2.

  • telescope (str) – The telescope to get visits for: “simonyi” or “auxtel”. Defaults to “simonyi”.

  • columns (Sequence) – A sequence of columns from the simulation to include.

  • max_simulation_age (int or None) – Age of oldest simulation to consider.

Returns:

visits – The visits from the prenight simulation.

Return type:

pd.DataFrame

rubin_sim.sim_archive.fetch_sim_for_nights(first_day_obs=None, last_day_obs=None, which_sim=None, stackers=(), get_sim_data_kwargs=None)[source]#

Fetches visit metadata from an opsim database for specified nights.

Parameters:
  • first_day_obs (str or None) – The date of the evening for the first night for which to get a simulation. If None, then the current date will be used.

  • last_day_obs (str or None) – The date of the evening for the last night for which to get a simulation. If None, then the current date will be used.

  • which_sim (ResourcePath or str or dict on None) – The resourcePath or URL of the opsim file from which to load visits, or the arguments to find_latest_prenight_sim_for_nights to use to determine which simulation to load. None uses default arguments to find_latest_prenight_sim_for_nights. Defaults to None.

  • stackers (Sequence[BaseStacker]) – A sequence of maf stackers to apply.

  • get_sim_data_kwargs (dict) – Additional arguments to get_sim_data to use to load the visits.

Returns:

visits – A pandas DataFrame containing visit parameters.

Return type:

pd.DataFrame

rubin_sim.sim_archive.fetch_sim_stats_for_night(day_obs=None, tags=('ideal', 'nominal'), telescope='simonyi', max_simulation_age=2, host=None, user=None, database=None, schema=None, prenight_index_path=None)[source]#

Count the visits on a night in the latest nominal sim for a night.

Parameters:
  • day_obs (str or ‘int’ or None) – Integer dayobs (int(YYYYMMDD)) or ISO string (YYYY-MM-DD) or None (day_obs including the evening of yesterday in local time).

  • tags (tuple[str]) – A tuple of tags to filter simulations by. Defaults to ('ideal', 'nominal').

  • telescope (str) – The telescope to search for (simonyi or auxtel). Defaults to simonyi.

  • max_simulation_age (int) – The maximum age of simulations to consider, in days. Simulations older than max_simulation_age will not be considered. Defaults to 2.

  • host (str or None, optional) – Database host address.

  • user (str or None, optional) – Database user name.

  • database (str or None, optional) – Database name.

  • schema (str or None, optional) – The schema in the database to use.

  • prenight_index_path (str or ResourcePath, optional) – Root path to the bucket files (used only if the database call fails).

Returns:

sim_stats – A dict with statistics for the night. Returns an empty dict when no statistics are availble.

Return type:

dict

rubin_sim.sim_archive.find_latest_prenight_sim_for_nights(first_day_obs=None, last_day_obs=None, tags=('ideal', 'nominal'), telescope='simonyi', max_simulation_age=2, get_prenight_index_kwargs=None)[source]#

Find the most recent prenight simulation that covers a night.

Parameters:
  • first_day_obs (str or None) – The date of the evening for the first night for which to get a simulation. If None, then the current date will be used.

  • last_day_obs (str or None) – The date of the evening for the last night for which to get a simulation. If None, then the current date will be used.

  • tags (tuple[str]) – A tuple of tags to filter simulations by. Defaults to ('ideal', 'nominal').

  • telescope (str) – The telescope to search for (simonyi or auxtel). Defaults to simonyi.

  • max_simulation_age (int) – The maximum age of simulations to consider, in days. Simulations older than max_simulation_age will not be considered. Defaults to 2.

  • get_prenight_index_kwargs (Optional[dict], default: None)

Returns:

sim_metadata – A dictionary with metadata for the simulation.

Return type:

dict

Raises:

NoMatchingSimulationsFoundError – If no prenight simulations match the requested criteria.

rubin_sim.sim_archive.get_prenight_index(day_obs, telescope='simonyi', schema=None, host=None, user=None, database=None, prenight_index_path=None)[source]#

Retrieve the pre‑night observation index for a given night.

Parameters:
  • day_obs (str or int or date) – Night for which to fetch the index. The function will return all simulations that simulate the night designated by the day_obs.

  • telescope (str) – Telescope name (default simonyi).

  • schema (str or None, optional) – Optional database schema name.

  • host (str or None, optional) – Database host address.

  • user (str or None, optional) – Database user name.

  • database (str or None, optional) – Database name.

  • prenight_index_path (str or ResourcePath, optional) – Root path to the bucket files (used only if the database call fails).

Returns:

prenights – Pre‑night index indexed by visitseq_uuid.

Return type:

pd.DataFrame

rubin_sim.sim_archive.get_scheduler(config_repo=None, config_script=None, config_ref='main', visits_db=None)[source]#

Generate a CoreScheduler according to a configuration.

Parameters:
  • config_repo (str) – The git repository with the configuration.

  • config_script (str) – The configuration script path (relative to the repository root).

  • config_ref (str, optional) – The branch of the repository to use, by default “main”

  • visits_db (str or None) – Database from which to load pre-existing visits

Returns:

scheduler – An instance of the Rubin Observatory FBS.

Return type:

CoreScheduler

Raises:

ValueError – If the config file is invalid, or has invalid content.

rubin_sim.sim_archive.get_scheduler_from_config(config_script_path)[source]#

Generate a CoreScheduler according to a configuration in a file.

Parameters:

config_script_path (str) – The configuration script path

Return type:

Tuple[int, CoreScheduler]

Returns:

  • nside (int) – The nside.

  • scheduler (CoreScheduler) – An instance of the Rubin Observatory FBS.

Raises:

ValueError – If the config file is invalid, or has invalid content.

rubin_sim.sim_archive.get_scheduler_instance_from_repo(config_repo, config_script, config_ref='main')[source]#

Generate a CoreScheduler according to a configuration in git.

Parameters:
  • config_repo (str) – The git repository with the configuration.

  • config_script (str) – The configuration script path (relative to the repository root).

  • config_ref (str, optional) – The branch of the repository to use, by default “main”

Returns:

scheduler – An instance of the Rubin Observatory FBS.

Return type:

CoreScheduler

Raises:

ValueError – If the config file is invalid, or has invalid content.

rubin_sim.sim_archive.get_sim_metadata(visitseq_uuid, day_obs=None, vsmd=None, **kwargs)[source]#

Get metadata for a simulation given its observation night and UUID.

Parameters:
  • visitseq_uuid (uuid.UUID or str) – The UUID of the simulation to retrieve information for.

  • day_obs (int or str or date or None) – The observation night for which to search for the simulation. Can be a date string, YYYYMMDD encoded into an integer, or a datetime.date object. The date rollover follows SITCOMTN-032 (-12hr timezone). This can be any night included in the simulation.

  • **kwargs (Any) – Additional keyword arguments passed to get_prenight_index().

  • vsmd (Optional[VisitSequenceArchiveMetadata], default: None)

Returns:

info – A Series containing the index information for the simulation.

Return type:

pandas.Series

Raises:

ValueError – If no simulation with the given UUID is found, or if multiple simulations are found with the same UUID (indicating a problem in the metadata database).

rubin_sim.sim_archive.get_sim_uuid(sim_date, daily_id, day_obs=None, vsmd=None, **kwargs)[source]#

Get the UUID of a simulation given its observation night, creation date, and daily ID.

Parameters:
  • sim_date (date) – The creation date of the simulation to find.

  • daily_id (int or str) – The daily ID of the simulation to find. The daily ID is an index of simulations in the metadata added at a given sim_date: A simulation with sim_date of 2026-04-28 and daily_id of 4 is the 4th simulation added to the metadata database with a creation date of 2026-04-28. The combination sim_date and daily_id uniquely identifies a simulation in a given metadata database, but unlike UUID is not guaranteed to be unique across different metadata databases.

  • day_obs (int or str or date or None) – The dayobs of a night simulated by the simulation. Can be a date string, YYYYMMDD encoded into an integer, or a datetime.date object. The date rollover follows SITCOMTN-032 (-12hr timezone). If None, the metadata database must be used.

  • vsmd (VisitSequenceArchiveMetadata or None) – The interface to the visit sequence metadata database to query.

  • **kwargs (Any) – Additional keyword arguments passed to get_prenight_index().

Returns:

uuid – The UUID of the matching simulation.

Return type:

uuid.UUID

Raises:

ValueError – If no simulation is found matching the specified criteria.

rubin_sim.sim_archive.get_visits(visits_url, query='', stackers=())[source]#

Retrieve visits for a visit sequence.

Parameters:
  • visits_url (str) – The origin of the visits.

  • query (str) – A query in pandas.DataFrame.query syntax to select visits from the returned sequence. Applied before stackers are run.

  • stackers (Sequence [BaseStacker]) – A sequence of maf stackers to apply.

Returns:

visits – The visits in the sequence.

Return type:

pd.DataFrame

rubin_sim.sim_archive.make_sim_data_dir(observations, reward_df=None, obs_rewards=None, in_files={}, sim_runner_kwargs={}, tags=[], label=None, data_path=None, opsim_metadata=None)[source]#

Create or fill a local simulation archive directory.

Parameters:
  • observations (np.recarray) – The observations data, in the “obs” format as accepted and created by SchemaConverter.

  • reward_df (pd.DataFrame, optional) – The reward data, by default None.

  • obs_rewards (pd.DataFrame, optional) – The observation rewards data, by default None.

  • in_files (dict, optional) – Additional input files to be included in the archive, by default {}.

  • sim_runner_kwargs (dict, optional) – Additional simulation runner keyword arguments, by default {}.

  • tags (list [str], optional) – A list of tags/keywords to be included in the metadata, by default [].

  • label (str, optional) – A label to be included in the metadata, by default None.

  • data_path (str or Path, optional) – The path to the simulation archive directory, by default None.

  • opsim_metadata (dict) – Metadata to be included.

Returns:

data_dir – The temporary directory containing the simulation archive.

Return type:

Path or TemporaryDirectory

rubin_sim.sim_archive.save_scheduler(scheduler, file_name)[source]#

Save an instances of the scheduler in a pickle file, compressed according to its extension.

Parameters:
  • scheduler (CoreScheduler) – The scheduler to save.

  • file_name (str) – The file in which to save the schedulers.

Return type:

None

rubin_sim.sim_archive.select_latest_prenight_sim(prenights, tags=('ideal', 'nominal'), max_simulation_age=2)[source]#

Select the best prenight simulation from a DataFrame.

Parameters:
  • prenights (pd.DataFrame) – The table of prenights from which to select.

  • tags (tuple [str]) – A tuple of tags to filter simulations by. Defaults to ('ideal', 'nominal').

  • max_simulation_age (int) – The maximum age of simulations to consider, in days. Simulations older than max_simulation_age will not be considered. Defaults to 2.

Returns:

best_sim – A dictionary with metadata for the simulation.

Return type:

dict or None