splan
Module that defines the SemesterPlanner class. This class is responsible for defining, building, and solving the Gurobi model for semester-level observation planning. It is nearly completely agnostic to all astronomy knowledge.
- class astroq.splan.SemesterPlanner(cf, run_band3)[source]
Bases:
objectDefine the SemesterPlanner object. This is the heart of AstroQ. This object: - manages and holds the parameters defined in the config.ini - constructs additional metadata for easy sharing/storage across functions - builds the Gurobi model - defines the constraints - sets the objective function - kicks off the model solver - serializes the results to a csv file - saves the object to an hdf5 file for use later by the nplan and plot modules
- _build_date_dictionary()[source]
Construct useful data structures that are used throughout the semester planner.
- Returns:
a dictionary where keys are the dates in the semester and values are the day index all_dates_array (list): a list of the dates in the semester
- Return type:
all_dates_dict (dict)
- _build_observability()[source]
Determine the indices of the slots where targets are observable using the Access object.
- Returns:
a dictionary where keys are the star names and values are the indices of the slots where the target is observable
- Return type:
observability (dict)
- _build_slots_required_dictionary(always_round_up_flag=False)[source]
Determine the number of slots required to complete for each visit of a given request.
- Returns:
a dictionary where keys are the star names and values are the number of slots required for each exposure
- Return type:
slots_needed_for_exposure_dict (dict)
- _calculate_slot_info()[source]
Compute important numbers relating to the quantity of slots.
- Returns:
None
- _compute_slots_required_for_exposure(exposure_time, slot_size, always_round_up_flag)[source]
Compute the number of slots required for a given exposure time.
- Parameters:
exposure_time – Exposure time in minutes
slot_size – Slot size in minutes
always_round_up_flag – If True, always round up to the next slot
- Returns:
the number of slots required for the given exposure time
- Return type:
slots_needed (int)
- build_model_round1()[source]
Implement the constraints and objective function for Round 1 as described in Lubin et al. 2025.
- Returns:
None
- build_model_round2()[source]
Implement the constraints and objective function for Round 2. Not described in Lubin et al. 2025.
- Returns:
None
- constraint_build_enforce_intranight_cadence()[source]
Constraint 4 in Lubin et al. 2025.
Ensure that the minimum number of hours pass between consecutive observations of a given target on the same night. If a target is scheduled for observation at a given time, prevent it from being scheduled again until the minimum number of hours have passed.
- constraint_build_theta_multivisit()[source]
See Equation 3 in Lubin et al. 2025.
Definition of the “shortfall” matrix, Theta. The shortfall is defined for each target, giving for each target the difference between the number of requested nights for that target and the sum of the past and future scheduled observations of that target.
- constraint_enforce_internight_cadence()[source]
See Constraint 3 in Lubin et al. 2025.
Ensure that the minimum number of days pass between consecutive observations of a given target. If a target is scheduled for observation on a given date, prevent it from being scheduled again until the minimum number of days have passed.
- constraint_fix_previous_objective(epsilon=0.03)[source]
Bonus round constraint: not featured in Lubin et al. 2025.
This constraint ensures that the objective function value calculated during Round 2 be within a given tolerance of the Round 1 value. This constraint ensures that Round 2 result in only small changes to the optimal solution found in Round 1.
- constraint_reserve_multislot_exposures()[source]
See Constraint 1 in Lubin et al. 2025.
Reserve multiple time slots for exposures that require more than one time slot to complete, and ensure that no other observations are scheduled during these slots.
- constraint_set_max_absolute_unique_nights_Wrd()[source]
Bonus round constraint: not featured in Lubin et al. 2025.
Set the maximum number of observations for a target to 150% of the original requested number.
- constraint_set_max_desired_unique_nights_Wrd()[source]
See Constraint 2 in Lubin et al. 2025.
Limit the number of observations scheduled for a given target to the maximum value provided by the PI. This constraint may later be relaxed if Round 2 of scheduling is invoked.
- constraint_set_min_max_visits_per_night()[source]
See Constraint 5 in Lubin et al. 2025.
Require that the number of scheduled visits to a target in a given night falls between the minimum and maximum values supplied by the PI.
- constraint_throttle()[source]
Not described in Lubin et al. 2025.
Ensure that no program is scheduled for more time than they bring to the queue, within a grace amount, decided by the observatory. There is one constraint per program.
- classmethod from_hdf5(hdf5_path)[source]
Load a SemesterPlanner object from an HDF5 file.
- Parameters:
hdf5_path (str) – Path to the HDF5 file
- Returns:
Reconstructed SemesterPlanner object
- Return type:
- remove_constraint_set_max_desired_unique_nights_Wrd()[source]
Bonus round constraint: not featured in Lubin et al. 2025.
Remove the maximum number of observations set by constraints_set_max_desired_unique_nights_Wrd.
- set_objective_maximize_slots_used()[source]
Bonus round constraint: not featured in Lubin et al. 2025.
In Round 2, maximize the number of filled slots, i.e., slots during which an exposure occurs.