lightcurvelynx.simulate

The core functions for running the LightCurveLynx simulation.

Attributes

logger

Classes

SimulationInfo

A class to hold all the information (data and configuration) for a simulation

Functions

get_time_windows(t0, z, obs_time_window_offset, ...)	Get the time windows for each sample state based on the time window offset.
simulate_lightcurves(model, num_samples, survey_info)	Generate a number of simulations of the given model and information
compute_single_noise_free_lightcurve(model, ...[, ...])	Compute the noise-free light curve for a single object.
compute_noise_free_lightcurves(model, graph_state, ...)	Compute the noise-free light curves for a given model and one more more states

Module Contents

logger

class SimulationInfo(model, num_samples, survey_info, *, obstable_save_cols=None, param_cols=None, obs_time_window_offset=None, rest_time_window_offset=None, apply_saturation=True, sample_offset=0, rng=None, output_file_path=None, save_full_filter_names=False, progress_bar=True, **kwargs)

A class to hold all the information (data and configuration) for a simulation run. This includes the model, the surveys, the passbands, etc. This object is used so we have have a single object to pass around to multiprocessing functions.

model

The model to draw from. This may have its own parameters which will be randomly sampled with each draw.

Type:

BasePhysicalModel

num_samples

The number of samples.

Type:

int

survey_info

The SurveyInfo objects from which to extract information for the samples.

Type:

List of SurveyInfo

obs_time_window_offset

A tuple specifying the observer-frame time window offset (start, end) relative to t0 in days. This is used to filter the observations to only those within the specified observer-frame time window (t0 + start, t0 + end). If None or the model does not have a t0 specified, no time window is applied.

Type:

tuple(float, float), optional

rest_time_window_offset

A tuple specifying the rest-frame time window offset (start, end) relative to t0 in days. This is used to filter the observations to only those within the specified rest-frame time window (t0 + start, t0 + end). If None or the model does not have a t0 and redshift specified, no time window is applied.

Type:

tuple(float, float), optional

apply_saturation

Whether to apply saturation thresholds from the ObsTable.

Type:

bool

obstable_save_cols

A list of ObsTable columns to be saved as part of the results. This is used to save context information about how the light curves were generated. If the column is missing from one of the ObsTables, a null value such as None or NaN is used. If None, no additional columns are saved.

Type:

list of str, optional

param_cols

A list of the model’s parameter columns to be saved as separate columns in the results (instead of just the full dictionary of parameters). These must be specified as strings in the node_name.param_name format. If None, no additional columns are saved.

Type:

list of str, optional

rng

A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.

Type:

numpy.random._generator.Generator, optional

sample_offset

An offset to apply to the sample indices. This is used when splitting the simulation into multiple batches for multiprocessing.

Type:

int

output_file_path

The file path and name of where to save the results. If provided the results are saved to this file instead of being returned directly.

Type:

str or Path, optional

save_full_filter_names

Whether to save the full filter names in the results (including survey prefix).

Type:

bool

progress_bar

Whether to show a progress bar during the simulation.

Type:

bool

kwargs

Additional keyword arguments to pass to the simulation function.

Type:

dict

model

num_samples

survey_info

obs_time_window_offset = None

rest_time_window_offset = None

apply_saturation = True

obstable_save_cols = None

param_cols = None

sample_offset = 0

rng = None

kwargs

output_file_path = None

save_full_filter_names = False

progress_bar = True

split(num_batches=None, batch_size=None)

Split the simulation info into multiple batches for parallel processing.

Parameters:

• num_batches (int, optional) – The number of batches to split the simulation into. If None, batch_size must be provided.

• batch_size (int, optional) – The size of each batch. If None, num_batches must be provided.

Returns:

batches – A list of SimulationInfo objects, one for each batch.

Return type:

list of SimulationInfo

get_time_windows(t0, z, obs_time_window_offset, rest_time_window_offset)

Get the time windows for each sample state based on the time window offset.

Parameters:

• t0 (float or np.ndarray, optional) – The reference time (t0) for the time windows.

• z (float or np.ndarray, optional) – The redshift for the time windows.

• obs_time_window_offset (tuple(float, float), optional) – A tuple specifying the observer-frame time window offset (start, end) relative to t0 in days. If None, no time window is applied.

• rest_time_window_offset (tuple(float, float), optional) – A tuple specifying the rest-frame time window offset (start, end) relative to t0 in days. If None, no time window is applied.

Returns:

• start_times (np.ndarray or None) – The start times for each sample (t0 + an offset) in the observer frame. If a before time is given, this is always returned as an array (even if t0 is a scalar). None returned if there is no start time.

• end_times (np.ndarray or None) – The end times for each sample (t0 + an offset) in the observer frame. If an after time is given, this is always returned as an array (even if t0 is a scalar). None returned if there is no end time.

simulate_lightcurves(model, num_samples, survey_info, passbands=None, *, obstable_save_cols=None, param_cols=None, obs_time_window_offset=None, rest_time_window_offset=None, apply_saturation=True, output_file_path=None, rng=None, executor=None, num_jobs=None, batch_size=100000, save_full_filter_names=False, progress_bar=True)

Generate a number of simulations of the given model and information from one or more surveys. The result data can either be returned directly (as a single nested data frame) or saved to file(s).

The columns in the return NestedFrame can include a mix of default information from the source object (e.g., ra, dec, t0, redshift), a nested lightcurve table, a saved parameters data block (with all the model’s parameters), and any additional user-specified values.

Parameters:

• model (BasePhysicalModel) – The model to draw from. This may have its own parameters which will be randomly sampled with each draw. This object’s parameters (e.g., ra, dec) will be saved to the result columns.

• num_samples (int) – The number of samples.

• survey_info (SurveyInfo, ObsTable, List of SurveyInfo, or List of ObsTable) – The SurveyInfo object(s) from which to extract information for the samples. If ObsTables are passed instead, they will be converted to SurveyInfo objects internally using the default passband group and noise model information. This functionality is provided for API backwards compatibility and will be removed in a future version.

• passbands (PassbandGroup, Spectrograph or List of (PassbandGroup, Spectrograph), optional) – This is unused and just provided for API backwards compatibility. It will be removed in a future version.

• obs_time_window_offset (tuple(float, float), optional) – A tuple specifying the observer-frame time window offset (start, end) relative to t0 in days. This is used to filter the observations to only those within the specified observer-frame time window (t0 + start, t0 + end). If None or the model does not have a t0 specified, no time window is applied. May not be used together with rest_time_window_offset.

• rest_time_window_offset (tuple(float, float), optional) – A tuple specifying the rest-frame time window offset (start, end) relative to t0 in days. This is used to filter the observations to only those within the specified rest-frame time window (t0 + start, t0 + end). If None or the model does not have a t0 and redshift specified, no time window is applied. May not be used together with obs_time_window_offset.

• apply_saturation (bool) – Whether to apply saturation thresholds from the ObsTable.

• obstable_save_cols (list of str, optional) – A list of ObsTable columns to be saved as part of the results. This is used to save context information about how the light curves were generated. If the column is missing from one of the ObsTables, a null value such as None or NaN is used. If None, no additional columns are saved.

• param_cols (list of str, optional) – A list of the model’s parameter columns to be saved as separate columns in the results (instead of just the full dictionary of parameters). These must be specified as strings in the node_name.param_name format. If None, no additional columns are saved.

• output_file_path (str or Path, optional) – The file path and name of where to save the results. If provided the results are saved to this file instead of being returned directly. If the simulation is run in parallel, multiple files are created with a _partN suffix.

• rng (numpy.random._generator.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.

• executor (concurrent.futures.Executor, optional) – The executor object that to use for parallel processing. This can be any object that supports concurrent.futures’s map() function, returning either Future objects or direct results. If None, the function runs in serial.

• num_jobs (int, optional) – If provided (and no executor is provided) creates a process pool (ProcessPoolExecutor) with the given number of workers to process the results.

• batch_size (int, optional) – The number of samples to process in each batch when using multiprocessing. Default is 100_000.

• save_full_filter_names (bool) – Whether to save the full filter names in the results (including survey prefix).

• progress_bar (bool) – Whether to show a progress bar during the simulation.

Returns:

lightcurves – If output_file_path is None, a NestedFrame with a row for each object. Otherwise the file(s) are saved and the function returns a list of Paths to the saved files.

Return type:

nested_pandas.NestedFrame or list of Path

compute_single_noise_free_lightcurve(model, graph_state, passbands, *, rest_frame_phase_min=-50.0, rest_frame_phase_max=50.0, rest_frame_phase_step=2.0)

Compute the noise-free light curve for a single object.

This is a helper function for compute_noise_free_lightcurves.

Parameters:

• model (BasePhysicalModel) – The model object to use for generating the light curves.

• graph_state (GraphState) – The state of the graph for the simulation. Must be a single state (num_samples=1).

• passbands (PassbandGroup) – The passbands to use for generating the bandfluxes.

• rest_frame_phase_min (float or np.ndarray) – The minimum rest-frame phase (in days) at which to evaluate the light curve. If an array is given, it must match the number of samples in graph_state. Default is -50.0 days.

• rest_frame_phase_max (float or np.ndarray) – The maximum rest-frame phase (in days) at which to evaluate the light curve. If an array is given, it must match the number of samples in graph_state. Default is 50.0 days.

• rest_frame_phase_step (float or np.ndarray) – The step size (in days) between rest-frame phases at which to evaluate the light curve. If an array is given, it must match the number of samples in graph_state. Default is 2.0 days.

Returns:

lightcurves – A dictionary mapping each filter name to the corresponding array of bandfluxes (in nJy), with an additional keys “times” (in MJD) and “rest_phase” (in days relative to t0).

Return type:

dict

compute_noise_free_lightcurves(model, graph_state, passbands, *, rest_frame_phase_min=-50.0, rest_frame_phase_max=50.0, rest_frame_phase_step=2.0)

Compute the noise-free light curves for a given model and one more more states at given times (in either MJD or rest-frame phase).

This function simulates the light curves without adding any noise, allowing for the analysis of the underlying model behavior.

Parameters:

• model (BasePhysicalModel) – The model object to use for generating the light curves.

• graph_state (GraphState) – The state of the graph for the simulation.

• passbands (PassbandGroup) – The passbands to use for generating the bandfluxes.

• rest_frame_phase_min (float or np.ndarray) – The minimum rest-frame phase (in days) at which to evaluate the light curve. If an array is given, it must match the number of samples in graph_state. Default is -50.0 days.

• rest_frame_phase_max (float or np.ndarray) – The maximum rest-frame phase (in days) at which to evaluate the light curve. If an array is given, it must match the number of samples in graph_state. Default is 50.0 days.

• rest_frame_phase_step (float or np.ndarray) – The step size (in days) between rest-frame phases at which to evaluate the light curve. If an array is given, it must match the number of samples in graph_state. Default is 2.0 days.

Returns:

lightcurves – A NestedFrame with a row for each object that contains a “lightcurve” column with a dictionary mapping each filter name to the corresponding array of bandfluxes (in nJy), with an additional nested columns “times” (in MJD) and “rest_phase” (in days relative to t0).

Return type:

nested_pandas.NestedFrame