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:
objectCallable 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 (
strorNone, optional) – The distribution from which the scatter should be taken. This must be the name of a method ofnumpy.random.Generator. IfNone, the distribution is taken fromDEFAULT_OVERHEAD_SCATTER_DIST. Defaults toNone.scatter_kwargs (
dictorNone, optional) – Dictionary of arguments passed toscatter_distribution. IfNone, the argumentns taken fromDEFAULT_OVERHEAD_SCATTER_KWARGS.min_overhead (
float, optional) – The minimum possible overhead
Notes
The
slew_scaleandslew_locparameters introduce an offset proportional to the slew time following a normal distribution. A non-zeroslew_locwill sysetmatically move the center of the distribution.The
visit_scaleandvisit_locparameters are no longer functional, and persist only to support backward compatibility.The
scatter_distributionandscatter_kwargsintroduce an offset independent of the modeled slew and visit times, and support any distribution offered bynumpy.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, theoffsethere 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:
ExceptionRaised when no simulations match requested criteria.
- class rubin_sim.sim_archive.VisitSequenceArchiveMetadata(metadata_db_kwargs=None, metadata_db_schema=None)[source]#
Bases:
objectInterface to metadata database that tracks sequences of visits.
- Parameters:
metadata_db_kwargs (
MappingorNone) – 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 topsycopg2.pool.SimpleConnectionPool. IfNone, the dictionary is built from the environment variablesVSARCHIVE_PGDATABASE,VSARCHIVE_PGHOST,VSARCHIVE_PGUSER, andVSARCHIVE_PGPORT(if they exist) or corresponding module variables inrubin_sim.sim_archive.vseqarchiv(if they do not).metadata_db_schema (
strorNone) – The schema in the database holding the metadata. IfNone, defaults torubin_sim.sim_archive.vseqarchive.VSARCHIVE_PGSCHEMA. Default isNone.
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 toNone.
- 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 bycompute_conda_env.- Returns:
env_exists –
Trueif a row with the supplied hash exists in theconda_envtable;Falseotherwise.- 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 (
dateonstrorint) – The creation date of the simulation to find, as a dayobs (utc-12 hour timezone)daily_id (
intorstr) – 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 withsim_dateof 2026-04-28 anddaily_idof 4 is the 4th simulation added to the metadata database with a creation date of 2026-04-28. The combinationsim_dateanddaily_iduniquely 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 (
strordatetime.date) – The ISO‑formatted date (e.g.'2025-03-12') or adateobject that identifies (with the sim_index) a simulation in the prototype archive.sim_index (
strorint) – 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 (
strorNone) – Base location of the archive to which to copy the visit sequence. IfNone, the visits will not be copied. Defaults toNone.
- 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
Falsefor 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) usingpsycopg2.sql.SQL.format. To make type checkers happy, you may need to explictly declare variables passed aslist[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 (
strorsql.SQL) – The query to senddata (
dict) – Data to include in the querycommit (
bool) – Commit the query (e.g. for an INSERT), defaults to Falsereturn_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 (
dateorintorstr, optional) – The first night of observations, defined according to SITCOMTN-032 (UTC-12hrs).last_day_obs (
dateorintorstr, 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 (
bytesorNone) – The SHA‑256 digest of the Conda environment JSON representation.None(the default) uses the current conda environment.conda_env_json (
strorNone) – 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 (
dateorintorstr) – The last day obs of the early parent.first_late_day_obs (
dateorintorstr) – 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 (
dateorintorstrorNone, optional) – The first night of observations, defined according to SITCOMTN-032 (UTC-12hrs).last_day_obs (
dateorintorstrorNone, optional) – The last day of observations, defined according to SITCOMTN-032 (UTC-12hrs).creation_time (
TimeorNone, 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 (
dateorintorstr, optional) – The first night of observations, defined according to SITCOMTN-032 (UTC-12hrs).last_day_obs (
dateorintorstr, 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 ofrubin_schedulerused to run the simulation, by default None.config_url (
str, optional) – URL for the config script, perhaps on github, by defaultNone.conda_env_sha256 (
bytes, optional) – SHA256 hash of output ofconda list --json, by default None.parent_visitseq_uuid (
UUID, optional) – UUID of visitseq loaded into scheduler before running, by defaultNone.sim_runner_kwargs (
dict, optional) – Arguments tosim_runneras adict, by defaultNone.parent_last_day_obs (
str, optional) – day_obs of last visit loaded into scheduler before running, by defaultNone.
- 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 ofsimulations,completed,mixedvisitseq, orvisitseq.url (
str, optional) – A URL for the file from thich the table of visits can be download.first_day_obs (
dateorintorstr, optional) – The first night of observations, defined according to SITCOMTN-032 (UTC-12hrs).last_day_obs (
dateorintorstr, 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_metadataandrecord_completed_metadatamethods 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 usingset_visitseq_url.file_sha256 (
bytes) – The hash of the file contents.location (
strorlsst.resources.ResourcePath) – The location of the file to be registered.update (
bool, optional) – IfTrueand a record for the samevisitseq_uuidandfile_typealready exists, the existing row will be updated with the new SHA‑256 hash and URL. IfFalseand a record already exists aValueErroris raised.
- Raises:
ValueError – If
file_typeis"visits"(useset_visitseq_urlinstead), or ifupdateisFalseand a record already exists for the givenvisitseq_uuidandfile_type.TypeError – If
locationis neither a string nor aResourcePath.
- 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 issimonyi.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 adatetime.dateobject, an ISO‑formatted string (e.g.'2025-12-01'), or an integer in SMTN‑032 format (e.g.20251201). IfNone(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 asfirst_day_obs. IfNonethe same value asfirst_day_obsis 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 issimonyi.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 tofield. 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 (
listofstr, 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 ifrecord_rewardsorscheduler.keep_rewardsis True.obs_rewards (
pandas.Series, optional) – The mapping of entries in reward_df to observations. Present ifrecord_rewards`orscheduler.keep_rewardsis True.resource_path (
ResourcePath, optional) – The resource path to the archive of the simulation. Present ifarchive_uriwas set.
Notes
Additional parameters not described above will be passed into
sim_runner.If the
archive_uriparameter is not supplied,sim_runneris run directly, so thatdrive_simcan act as a drop-in replacement ofsim_runner.In a jupyter notebook, the notebook can be saved for the notebook paramater using
%notebook $notebook_fname(wherenotebook_fnameis variable holding the filename for the notebook) in the cell prior to callingdrive_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 (
intorNone) – 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 (
strorNone) – The date of the evening for the first night for which to get a simulation. IfNone, then the current date will be used.last_day_obs (
strorNone) – The date of the evening for the last night for which to get a simulation. IfNone, then the current date will be used.which_sim (
ResourcePathorstrordictonNone) – TheresourcePathor URL of the opsim file from which to load visits, or the arguments tofind_latest_prenight_sim_for_nightsto use to determine which simulation to load.Noneuses default arguments tofind_latest_prenight_sim_for_nights. Defaults toNone.stackers (
Sequence[BaseStacker]) – A sequence of maf stackers to apply.get_sim_data_kwargs (
dict) – Additional arguments toget_sim_datato 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 (
stror ‘int’ orNone) – Integer dayobs (int(YYYYMMDD)) or ISO string (YYYY-MM-DD) orNone(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 thanmax_simulation_agewill not be considered. Defaults to 2.host (
strorNone, optional) – Database host address.user (
strorNone, optional) – Database user name.database (
strorNone, optional) – Database name.schema (
stror None, optional) – The schema in the database to use.prenight_index_path (
strorResourcePath, 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 (
strorNone) – The date of the evening for the first night for which to get a simulation. IfNone, then the current date will be used.last_day_obs (
strorNone) – The date of the evening for the last night for which to get a simulation. IfNone, 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 thanmax_simulation_agewill 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 (
strorintordate) – 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 (defaultsimonyi).schema (
strorNone, optional) – Optional database schema name.host (
strorNone, optional) – Database host address.user (
strorNone, optional) – Database user name.database (
strorNone, optional) – Database name.prenight_index_path (
strorResourcePath, 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 (
strorNone) – 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.UUIDorstr) – The UUID of the simulation to retrieve information for.day_obs (
intorstrordateorNone) – The observation night for which to search for the simulation. Can be a date string, YYYYMMDD encoded into an integer, or adatetime.dateobject. The date rollover follows SITCOMTN-032 (-12hr timezone). This can be any night included in the simulation.**kwargs (
Any) – Additional keyword arguments passed toget_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 (
intorstr) – 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 withsim_dateof 2026-04-28 anddaily_idof 4 is the 4th simulation added to the metadata database with a creation date of 2026-04-28. The combinationsim_dateanddaily_iduniquely identifies a simulation in a given metadata database, but unlike UUID is not guaranteed to be unique across different metadata databases.day_obs (
intorstrordateorNone) – The dayobs of a night simulated by the simulation. Can be a date string, YYYYMMDD encoded into an integer, or adatetime.dateobject. The date rollover follows SITCOMTN-032 (-12hr timezone). IfNone, the metadata database must be used.vsmd (
VisitSequenceArchiveMetadataorNone) – The interface to the visit sequence metadata database to query.**kwargs (
Any) – Additional keyword arguments passed toget_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 inpandas.DataFrame.querysyntax 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 bySchemaConverter.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 (
strorPath, 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:
PathorTemporaryDirectory
- 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 thanmax_simulation_agewill not be considered. Defaults to 2.
- Returns:
best_sim – A dictionary with metadata for the simulation.
- Return type:
dictorNone