Full surveysim API Reference¶

Modules¶

surveysim.nightops¶

Simulate one night of observing.

surveysim.nightops.simulate_night(night, scheduler, stats, explist, weather, use_twilight=False, update_interval=10.0, plot=False, verbose=False)[source]¶

Simulate one night of observing.

Uses the online tile scheduler and exposure time calculator.

Parameters:

night (datetime.date) – Date that the simulated night starts.
scheduler (desisurvey.scheduler.Scheduler) – Next tile scheduler to use.
stats (surveysim.stats.SurveyStatistics) – Object for accumulating simulated survey statistics.
explist (surveysim.exposures.ExposureList) – Object for recording simulated exposures.
weather (surveysim.weather.Weather) – Simulated weather conditions to use.
use_twlight (bool) – Observe during twilight when True.
update_interval (float) – Interval in seconds for simulated ETC updates.
plot (bool) – Generate a plot summarizing the simulated night when True.
verbose (bool) – Produce verbose output on simulation progress when True.

surveysim.simulator¶

Top-level survey simulation manager.

class surveysim.simulator.Simulator(start_date, stop_date, progress, weather, stats, strategy, plan, gen=None)[source]¶

Initialize a survey simulation.

Parameters:

start_date (datetime.date) – Survey starts on the evening of this date.
stop_date (datetime.date) – Survey stops on the morning of this date.
progress (desisurvey.progress.Progress) – Progress of survey at the start of this simulation.
weather (surveysim.weather.Weather) – Simulated weather conditions use use.
stats (astropy.table.Table or None) – Table of per-night efficiency statistics to update.
strategy (str) – Strategy to use for scheduling tiles during each night.
plan (str) – Name of plan file to use.
gen (numpy.random.RandomState or None) – Random number generator to use for reproducible samples. Will be initialized (un-reproducibly) if None.

property date¶: The current simulation date as a datetime object.

next_day(scores=None)[source]¶

Simulate the next day of survey operations.

A day runs from local noon to local noon. A survey ends, with this method returning False, when either we reach the last scheduled day or else we run out of tiles to observe.

Returns:: True if there are more days to simulate.
Return type:: bool

surveysim.weather¶

Simulate stochastic observing weather conditions.

The simulated conditions include seeing, transparency and the dome-open fraction.

class surveysim.weather.Weather(seed=1, replay='random', time_step=5, restore=None, extra_downtime=0)[source]¶

Simulate weather conditions affecting observations.

The start/stop date range is taken from the survey config.

Seeing and transparency values are stored with 32-bit floats to save some memory.

Parameters:

seed (int) – Random number seed to use to generate stochastic conditions. The seed determines the same seeing and transparency realization independent of the value of replay.
replay (str) – Either ‘random’ or a comma-separated list of years whose historical weather should be replayed, e.g. ‘Y2010,Y2012’. Replayed weather will be used cyclically if necessary. Random weather will be a boostrap sampling of all available years with historical weather data. Use ‘Y2015’ for the worst-case weather scenario.
time_step (float or astropy.units.Quantity, optional) – Time step calculating updates. Must evenly divide 24 hours. If unitless float, will be interpreted as minutes.
restore (filename or None) – Restore an existing weather simulation from the specified file name. All other parameters are ignored when this is provided. A relative path name refers to the configuration output path.
extra_downtime (float) – Additionally close the dome completely on some nights. Nights are chosen randomly, with the chance of the night being closed equal to extra_random_close_fraction. This is intended to include margin.

get(time)[source]¶

Get the weather conditions at the specified time(s).

Returns the conditions at the closest tabulated time, rather than using interpolation.

Parameters:: time (astropy.time.Time) – Time(s) when the simulated weather is requested.
Returns:: Slice of precomputed table containing row(s) corresponding to the requested time(s).
Return type:: table slice

save(filename, overwrite=True)[source]¶

Save the generated weather to a file.

The saved file can be restored using the constructor restore parameter.

Parameters:

filename (str) – Name of the file where the weather should be saved. A relative path name refers to the configuration output path.
overwrite (bool) – Silently overwrite any existing file when this is True.

surveysim.util¶

Simulation utilities that may be used by other packages.

surveysim.util.add_calibration_exposures(exposures, flats_per_night=3, arcs_per_night=3, darks_per_night=0, zeroes_per_night=0, exptime=None, readout=30.0)[source]¶

Prepare a list of science exposures for desisim.wrap-newexp.

Insert calibration exposures at the start of each night, and add the following columns for all exposures: EXPID, PROGRAM, NIGHT, FLAVOR.

Parameters:

exposures (table like or surveysim.exposures.ExposureList) – A table of science exposures including, at a minimum, MJD, EXPTIME and TILEID columns. The exposures must be sorted by increasing MJD. Could be a numpy recarray, an astropy table, or an ExposureList object. Columns other than the required ones are copied to the output.
flats_per_night (int, optional) – Add this many arc exposures per night (default 3).
arcs_per_night (int, optional) – Add this many arc exposures per night (default 3).
darks_per_night (int, optional) – Add this many dark exposures per night (default 0).
zeroes_per_night (int, optional) – Add this many zero exposures per night (default 0).
exptime (dict, optional) – A dictionary setting calibration exposure times for each calibration flavor.
readout (float, optional) – Set readout time for calibration exposures (default 30.0 s).

Returns:

The output table augmented with calibration exposures and additional columns.

Return type:

astropy.table.Table

Raises:

ValueError – If the input is not sorted by increasing MJD/timestamp.

surveysim.stats¶

Record simulated nightly statistics by program.

class surveysim.stats.SurveyStatistics(start_date=None, stop_date=None, restore=None)[source]¶

Collect nightly statistics by program.

Parameters:

start_date (datetime.date or None) – Record statistics for a survey that starts on the evening of this date. Uses the configured nominal start date when None.
stop_date (datetime.date) – Record statistics for a survey that stops on the morning of this date. Uses the configured nominal stop date when None.
restore (str or None) – Restore internal state from the snapshot saved to this filename, or initialize a new object when None. Use save() to save a snapshot to be restored later. Filename is relative to the configured output path unless an absolute path is provided.

plot(forecast=None)[source]¶

Plot a summary of the survey statistics.

Requires that matplotlib is installed.

save(name='stats.fits', comment='', overwrite=True)[source]¶

Save a snapshot of these statistics as a binary FITS table.

The saved file size is ~800 Kb.

Parameters:

name (str) – File name to write. Will be located in the configuration output path unless it is an absolute path. Pass the same name to the constructor’s restore argument to restore this snapshot.
comment (str) – Comment to include in the saved header, for documentation purposes.
overwrite (bool) – Silently overwrite any existing file when True.

summarize(nthday=None)[source]¶: Print a tabular summary of the accumulated statistics to stdout.

surveysim.exposures¶

Record simulated exposures and collect per-tile statistics.

class surveysim.exposures.ExposureList(restore=None, max_nexp=60000, existing_exposures=None)[source]¶

Record simulated exposures and collect per-tile statistics.

Parameters:

restore (str or None) – Restore internal state from the snapshot saved to this filename, or initialize a new object when None. Use save() to save a snapshot to be restored later. Filename is relative to the configured output path unless an absolute path is provided.
max_nexp (int) – The maximum expected number of exposures, which determines the memory size of this object.

add(mjd, exptime, tileID, snr2frac, dsnr2frac, airmass, seeing, transp, sky)[source]¶

Record metadata for a single exposure.

Parameters:

mjd (float) – MJD timestamp at the start of the exposure.
tileID (int) – ID of the observed tile.
snr2frac (float) – Fractional SNR2 accumulated on this tile at the end of exposure.
dsnr2frac (float) – Fractional SNR2 accumulated on this tile during this exposure.
airmass (float) – Average airmass during this exposure.
seeing (float) – Average atmospheric seeing in arcseconds during this exposure.
transp (float) – Average atmospheric transparency during this exposure.
sky (float) – Average sky background level during this exposure.

save(name='exposures.fits', comment='', overwrite=True)[source]¶

Save exposures to a FITS file with two binary tables.

The saved file size scales linearly with the number of exposures added so far, and is independent of the memory size of this object.

Parameters:

name (str) – File name to write. Will be located in the configuration output path unless it is an absolute path. Pass the same name to the constructor’s restore argument to restore this snapshot.
comment (str) – Comment to include in the saved header, for documentation purposes.
overwrite (bool) – Silently overwrite any existing file when True.

update_tiles(night, available, planned)[source]¶

Update tile availability and planning status.

Parameters:

night (datetime.date) – Night of initial observing.
available (array) – Array of tile indices that are newly available since the last call to this method.
planned (array) – Array of tile indices that are newly planned (priority > 0) since the last call to this method.

Command-Line Scripts¶

surveysim¶

surveysim.scripts.surveysim¶

Script wrapper for running survey simulations.

Simulate a sequence of observations until either the nominal survey end date is reached, or all tiles have been observed. See doc/tutorial.rst for details.

To run this script from the command line, use the surveysim entry point that is created when this package is installed, and should be in your shell command search path.

surveysim.scripts.surveysim.main(args)[source]¶: Command-line driver for running survey simulations.

surveysim.scripts.surveysim.parse(options=None)[source]¶: Parse command-line options for running survey simulations.