Simulated Ground-Based Observing
Simulated Ground-Based Observing¶
Simulating observing with a ground-based telescope also consists of generating an observing schedule and using that schedule to simulate telescope pointing. A ground-based schedule contains a list of scans, each of which describes the high-level motion of the telescope for some length of time:
- class toast.schedule.GroundScan(name=None, start=None, stop=None, boresight_angle=<Quantity 0. deg>, az_min=<Quantity 0. deg>, az_max=<Quantity 0. deg>, el=<Quantity 0. deg>, rising=False, sun_az_begin=<Quantity 0. deg>, sun_az_end=<Quantity 0. deg>, sun_el_begin=<Quantity 0. deg>, sun_el_end=<Quantity 0. deg>, moon_az_begin=<Quantity 0. deg>, moon_az_end=<Quantity 0. deg>, moon_el_begin=<Quantity 0. deg>, moon_el_end=<Quantity 0. deg>, moon_phase=0.0, scan_indx=0, subscan_indx=0)¶
Simulated ground telescope scan properties for one observation.
- Parameters
name (str) – Arbitrary name (does not have to be unique).
start (datetime) – The start time of the scan.
stop (datetime) – The stop time of the scan.
boresight_angle (Quantity) – Boresight rotation angle.
az_min (Quantity) – The minimum Azimuth value of each sweep.
az_max (Quantity) – The maximum Azimuth value of each sweep.
el (Quantity) – The nominal Elevation of the scan.
rising (bool) – If True, the patch is rising, else it is setting.
sun_az_begin (Quantity) – The Sun Azimuth value at the beginning of the scan.
sun_az_end (Quantity) – The Sun Azimuth value at the end of the scan.
sun_el_begin (Quantity) – The Sun Elevation value at the beginning of the scan.
sun_el_end (Quantity) – The Sun Elevation value at the end of the scan.
moon_az_begin (Quantity) – The Moon Azimuth value at the beginning of the scan.
moon_az_end (Quantity) – The Moon Azimuth value at the end of the scan.
moon_el_begin (Quantity) – The Moon Elevation value at the beginning of the scan.
moon_el_end (Quantity) – The Moon Elevation value at the end of the scan.
moon_phase (float) – The phase of the moon as a value from 0 to 1.
scan_indx (int) – The current pass of this patch in the overall schedule.
subscan_indx (int) – The current sub-pass of this patch in the overall schedule.
- min_sso_dist(sso_az_begin, sso_el_begin, sso_az_end, sso_el_end)¶
Rough minimum angle between the boresight and a solar system object.
- Parameters
sso_az_begin (Quantity) – Object starting Azimuth
sso_el_begin (Quantity) – Object starting Elevation
sso_az_end (Quantity) – Object final Azimuth
sso_el_end (Quantity) – Object final Elevation
- Returns
The minimum angle.
- Return type
(Quantity)
- class toast.schedule.GroundSchedule(scans=None, site_name='Unknown', telescope_name='Unknown', site_lat=<Quantity 0. deg>, site_lon=<Quantity 0. deg>, site_alt=<Quantity 0. m>)¶
Class representing a ground based observing schedule.
A schedule is a collection of scans, with some extra methods for doing I/O.
- Parameters
scans (list) – A list of GroundScan instances or None.
site_name (str) – The name of the site for this schedule.
telescope_name (str) – The name of the telescope for this schedule.
site_lat (Quantity) – The site latitude.
site_lon (Quantity) – The site longitude.
site_alt (Quantity) – The site altitude.
- read(file, file_split=None, comm=None, sort=False)¶
Load a ground observing schedule from a file.
This loads scans from a file and appends them to the internal list of scans. The resulting combined scan list is optionally sorted.
- Parameters
file (str) – The file to load.
file_split (tuple) – If not None, only use a subset of the schedule file. The arguments are (isplit, nsplit) and only observations that satisfy ‘scan index modulo nsplit == isplit’ are included.
comm (MPI.Comm) – Optional communicator to broadcast the schedule across.
sort (bool) – If True, sort the combined scan list by name.
- Returns
None
Because ground schedules are more complex, they are usually generated with a commandline tool:
usage: toast_ground_schedule [-h] [--site-name SITE_NAME]
[--telescope TELESCOPE] [--site-lon SITE_LON]
[--site-lat SITE_LAT] [--site-alt SITE_ALT]
[--scan-margin SCAN_MARGIN]
[--ra-period RA_PERIOD]
[--ra-amplitude-deg RA_AMPLITUDE_DEG]
[--dec-period DEC_PERIOD]
[--dec-amplitude-deg DEC_AMPLITUDE_DEG]
[--elevation-penalty-limit ELEVATION_PENALTY_LIMIT]
[--elevation-penalty-power ELEVATION_PENALTY_POWER]
[--equalize-area] [--equalize-time]
[--equalize-scans] --patch PATCH
[--patch-coord PATCH_COORD]
[--el-min-deg EL_MIN_DEG]
[--el-max-deg EL_MAX_DEG]
[--el-step-deg EL_STEP_DEG] [--alternate]
[--fp-radius-deg FP_RADIUS_DEG]
[--sun-avoidance-angle-deg SUN_AVOIDANCE_ANGLE_DEG]
[--moon-avoidance-angle-deg MOON_AVOIDANCE_ANGLE_DEG]
[--sun-el-max-deg SUN_EL_MAX_DEG]
[--boresight-angle-step-deg BORESIGHT_ANGLE_STEP_DEG]
[--boresight-angle-time-min BORESIGHT_ANGLE_TIME_MIN]
[--start START] [--stop STOP]
[--block-out BLOCK_OUT]
[--operational-days OPERATIONAL_DAYS]
[--timezone TIMEZONE] [--gap-s GAP_S]
[--gap-small-s GAP_SMALL_S]
[--time-step-s TIME_STEP_S] [--one-scan-per-day]
[--ces-max-time-s CES_MAX_TIME_S] [--debug]
[--polmap POLMAP] [--pol-min POL_MIN]
[--pol-max POL_MAX] [--delay-sso-check]
[--pole-mode]
[--pole-el-step-deg POLE_EL_STEP_DEG]
[--pole-ces-time-s POLE_CES_TIME_S] [--out OUT]
[--boresight-offset-el-deg BORESIGHT_OFFSET_EL_DEG]
[--boresight-offset-az-deg BORESIGHT_OFFSET_AZ_DEG]
[--elevations-deg ELEVATIONS_DEG]
[--partial-scans] [--no-partial-scans]
[--pole-raster-scan]
[--pole-raster-el-step-deg POLE_RASTER_EL_STEP_DEG]
[--az-rate-sky-deg AZ_RATE_SKY_DEG]
[--az-accel-mount-deg AZ_ACCEL_MOUNT_DEG]
[--el-rate-deg EL_RATE_DEG]
[--el-accel-deg EL_ACCEL_DEG]
Generate ground observation schedule.
optional arguments:
-h, --help show this help message and exit
--site-name SITE_NAME
Observing site name
--telescope TELESCOPE
Observing telescope name
--site-lon SITE_LON Observing site longitude [PyEphem string]
--site-lat SITE_LAT Observing site latitude [PyEphem string]
--site-alt SITE_ALT Observing site altitude [meters]
--scan-margin SCAN_MARGIN
Random fractional margin [0..1] added to the scans to
smooth out edge effects
--ra-period RA_PERIOD
Period of patch position oscillations in RA [visits]
--ra-amplitude-deg RA_AMPLITUDE_DEG
Amplitude of patch position oscillations in RA [deg]
--dec-period DEC_PERIOD
Period of patch position oscillations in DEC [visits]
--dec-amplitude-deg DEC_AMPLITUDE_DEG
Amplitude of patch position oscillations in DEC [deg]
--elevation-penalty-limit ELEVATION_PENALTY_LIMIT
Assign a penalty to observing elevations below this
limit [degrees]
--elevation-penalty-power ELEVATION_PENALTY_POWER
Power in the elevation penalty function [> 0]
--equalize-area Adjust priorities to account for patch area
--equalize-time Modulate priority by integration time.
--equalize-scans Modulate priority by number of scans.
--patch PATCH Patch definition: name,weight,lon1,lat1,lon2,lat2 ...
OR name,weight,lon,lat,width
--patch-coord PATCH_COORD
Sky patch coordinate system [C,E,G]
--el-min-deg EL_MIN_DEG
Minimum elevation for a CES
--el-max-deg EL_MAX_DEG
Maximum elevation for a CES
--el-step-deg EL_STEP_DEG
Optional step to apply to minimum elevation
--alternate Alternate between rising and setting scans
--fp-radius-deg FP_RADIUS_DEG
Focal plane radius [deg]
--sun-avoidance-angle-deg SUN_AVOIDANCE_ANGLE_DEG
Minimum distance between the Sun and the bore sight
[deg]
--moon-avoidance-angle-deg MOON_AVOIDANCE_ANGLE_DEG
Minimum distance between the Moon and the bore sight
[deg]
--sun-el-max-deg SUN_EL_MAX_DEG
Maximum allowed sun elevation [deg]
--boresight-angle-step-deg BORESIGHT_ANGLE_STEP_DEG
Boresight rotation step size [deg]
--boresight-angle-time-min BORESIGHT_ANGLE_TIME_MIN
Boresight rotation step interval [minutes]
--start START UTC start time of the schedule
--stop STOP UTC stop time of the schedule
--block-out BLOCK_OUT
Range of UTC calendar days to omit from scheduling in
format START_MONTH/START_DAY-END_MONTH/END_DAY or
START_YEAR/START_MONTH/START_DAY-
END_YEAR/END_MONTH/END_DAY where YEAR, MONTH and DAY
are integers. END days are inclusive
--operational-days OPERATIONAL_DAYS
Number of operational days to schedule (empty days do
not count)
--timezone TIMEZONE Offset to apply to MJD to separate operational days
[hours]
--gap-s GAP_S Gap between CES:es [seconds]
--gap-small-s GAP_SMALL_S
Gap between split CES:es [seconds]
--time-step-s TIME_STEP_S
Time step after failed target acquisition [seconds]
--one-scan-per-day Pad each operational day to have only one CES
--ces-max-time-s CES_MAX_TIME_S
Maximum length of a CES [seconds]
--debug Write diagnostics, including patch plots.
--polmap POLMAP Include polarization from map in the plotted patches
when --debug
--pol-min POL_MIN Lower plotting range for polarization map
--pol-max POL_MAX Upper plotting range for polarization map
--delay-sso-check Only apply SSO check during simulated scan.
--pole-mode Pole scheduling mode (no drift scan)
--pole-el-step-deg POLE_EL_STEP_DEG
Elevation step in pole scheduling mode [deg]
--pole-ces-time-s POLE_CES_TIME_S
Time to scan at constant elevation in pole mode
--out OUT Output filename
--boresight-offset-el-deg BORESIGHT_OFFSET_EL_DEG
Optional offset added to every observing elevation
--boresight-offset-az-deg BORESIGHT_OFFSET_AZ_DEG
Optional offset added to every observing azimuth
--elevations-deg ELEVATIONS_DEG
Fixed observing elevations in a comma-separated list.
--partial-scans Allow partials scans when full scans are not
available.
--no-partial-scans Allow partials scans when full scans are not
available.
--pole-raster-scan Pole raster scan mode
--pole-raster-el-step-deg POLE_RASTER_EL_STEP_DEG
Elevation step in pole raster scheduling mode [deg]
--az-rate-sky-deg AZ_RATE_SKY_DEG
Azimuthal rate in pole raster scheduling mode [deg]
--az-accel-mount-deg AZ_ACCEL_MOUNT_DEG
Azimuthal accleration in pole raster scheduling mode
[deg]
--el-rate-deg EL_RATE_DEG
Elevation rate in pole raster scheduling mode [deg]
--el-accel-deg EL_ACCEL_DEG
Elevation accleration in pole raster scheduling mode
[deg]
This writes the schedule to a custom format that can later be loaded
before passing it to the SimGround operator:
- class toast.ops.SimGround(*, API=0, azimuth='azimuth', boresight_azel='boresight_azel', boresight_radec='boresight_radec', det_data='signal', det_flags='flags', detset_key=None, distribute_time=False, el_mod_amplitude=<Quantity 1. deg>, el_mod_rate=<Quantity 0. Hz>, el_mod_sine=False, el_mod_step=<Quantity 0. deg>, elevation='elevation', elnod_end=False, elnod_every_scan=False, elnod_interval='elnod', elnod_mask=7, elnod_start=False, elnods, enabled=True, hwp_angle=None, hwp_rpm=None, hwp_step=None, hwp_step_time=None, invalid_mask=1, leftright_mask=8, max_pwv=None, median_weather=False, name=None, position='position', realization=0, rightleft_mask=16, scan_accel_az=<Quantity 1. deg / s2>, scan_accel_el=<Quantity 1. deg / s2>, scan_cosecant_modulation=False, scan_leftright_interval='scan_leftright', scan_rate_az=<Quantity 1. deg / s>, scan_rate_el=<Quantity 1. deg / s>, scan_rightleft_interval='scan_rightleft', scanning_interval='scanning', schedule, shared_flags='flags', sun_angle_min=<Quantity 90. deg>, sun_close_distance=<Quantity 45. deg>, sun_close_interval='sun_close', sun_close_mask=64, sun_up_interval='sun_up', sun_up_mask=32, telescope, throw_interval='throw', throw_leftright_interval='throw_leftright', throw_rightleft_interval='throw_rightleft', times='times', timezone=0, turn_leftright_interval='turn_leftright', turn_rightleft_interval='turn_rightleft', turnaround_interval='turnaround', turnaround_mask=3, velocity='velocity', weather=None, **kwargs)¶
Simulate a generic ground-based telescope scanning.
This simulates ground-based pointing in constant elevation scans for a telescope located at a particular site and using an pre-created schedule.
The created observations define several interval lists to describe regions where the telescope is scanning left, right or in a turnaround or El-nod. A shared flag array is also created with bits sets for these same properties.
Note
The following traits can be set at construction or afterwards
- Variables
API (int) – Internal interface version for this operator (default = 0)
azimuth (str) – Observation shared key for Azimuth (default = ‘azimuth’)
boresight_azel (str) – Observation shared key for boresight AZ/EL (default = ‘boresight_azel’)
boresight_radec (str) – Observation shared key for boresight RA/DEC (default = ‘boresight_radec’)
det_data (str) – Observation detdata key to initialize (default = ‘signal’)
det_flags (str) – Observation detdata key for flags to initialize (default = ‘flags’)
detset_key (str) – If specified, use this column of the focalplane detector_data to group detectors (default = ‘None’)
distribute_time (bool) – Distribute observation data along the time axis rather than detector axis (default = False)
el_mod_amplitude (Quantity) – Range of elevation modulation (default = 1.0 deg)
el_mod_rate (Quantity) – Modulate elevation continuously at this rate (default = 0.0 Hz)
el_mod_sine (bool) – Modulate elevation with a sine wave instead of a triangle wave (default = False)
el_mod_step (Quantity) – Amount to step elevation after each left-right scan pair (default = 0.0 deg)
elevation (str) – Observation shared key for Elevation (default = ‘elevation’)
elnod_end (bool) – Perform an el-nod after the scan (default = False)
elnod_every_scan (bool) – Perform el nods every scan (default = False)
elnod_interval (str) – Interval name for elnods (default = ‘elnod’)
elnod_mask (int) – Bit mask to raise elevation nod flags with (default = 7)
elnod_start (bool) – Perform an el-nod before the scan (default = False)
elnods (list) – List of relative el_nods (default = traitlets.Undefined)
enabled (bool) – If True, this class instance is marked as enabled (default = True)
hwp_angle (str) – Observation shared key for HWP angle (default = ‘None’)
hwp_rpm (float) – The rate (in RPM) of the HWP rotation (default = None)
hwp_step (Quantity) – For stepped HWP, the angle of each step (default = None)
hwp_step_time (Quantity) – For stepped HWP, the time between steps (default = None)
invalid_mask (int) – Bit mask to raise invalid flags with (default = 1)
leftright_mask (int) – Bit mask to raise left-to-right flags with (default = 8)
max_pwv (Quantity) – Maximum PWV for the simulated weather. (default = None)
median_weather (bool) – Use median weather parameters instead of sampling from the distributions (default = False)
name (str) – The ‘name’ of this class instance (default = ‘None’)
position (str) – Observation shared key for position (default = ‘position’)
realization (int) – The realization index (default = 0)
rightleft_mask (int) – Bit mask to raise right-to-left flags with (default = 16)
scan_accel_az (Quantity) – Mount scanning rate acceleration for turnarounds (default = 1.0 deg / s2)
scan_accel_el (Quantity) – Mount elevation rate acceleration. (default = 1.0 deg / s2)
scan_cosecant_modulation (bool) – Modulate the scan rate according to 1/sin(az) for uniform depth (default = False)
scan_leftright_interval (str) – Interval name for left to right scans (default = ‘scan_leftright’)
scan_rate_az (Quantity) – The sky azimuth scanning rate (default = 1.0 deg / s)
scan_rate_el (Quantity) – The sky elevation scanning rate (default = 1.0 deg / s)
scan_rightleft_interval (str) – Interval name for right to left scans (default = ‘scan_rightleft’)
scanning_interval (str) – Interval name for scanning (default = ‘scanning’)
schedule (GroundSchedule) – Instance of a GroundSchedule (default = traitlets.Undefined)
shared_flags (str) – Observation shared key for common flags (default = ‘flags’)
sun_angle_min (Quantity) – Minimum angular distance for the scan and the Sun (default = 90.0 deg)
sun_close_distance (Quantity) – ‘Sun close’ flagging distance (default = 45.0 deg)
sun_close_interval (str) – Interval name for times when the sun is close (default = ‘sun_close’)
sun_close_mask (int) – Bit mask to raise Sun close flags with (default = 64)
sun_up_interval (str) – Interval name for times when the sun is up (default = ‘sun_up’)
sun_up_mask (int) – Bit mask to raise Sun up flags with (default = 32)
telescope (Telescope) – This must be an instance of a Telescope (default = traitlets.Undefined)
throw_interval (str) – Interval name for scan + turnaround intervals (default = ‘throw’)
throw_leftright_interval (str) – Interval name for left to right scans + turnarounds (default = ‘throw_leftright’)
throw_rightleft_interval (str) – Interval name for right to left scans + turnarounds (default = ‘throw_rightleft’)
times (str) – Observation shared key for timestamps (default = ‘times’)
timezone (int) – The (integer) timezone offset in hours from UTC to apply to schedule (default = 0)
turn_leftright_interval (str) – Interval name for turnarounds after left to right scans (default = ‘turn_leftright’)
turn_rightleft_interval (str) – Interval name for turnarounds after right to left scans (default = ‘turn_rightleft’)
turnaround_interval (str) – Interval name for turnarounds (default = ‘turnaround’)
turnaround_mask (int) – Bit mask to raise turnaround flags with (default = 3)
velocity (str) – Observation shared key for velocity (default = ‘velocity’)
weather (str) – Name of built-in weather site (e.g. ‘atacama’, ‘south_pole’) or path to HDF5 file (default = ‘None’)