satsim package¶
Top-level package for SatSim.
Subpackages¶
Submodules¶
satsim.cli module¶
satsim.config module¶
-
satsim.config.
dict_merge
(dct, merge_dct)¶ Recursive dict merge. Inspired by
dict.update()
, instead of updating only top-level keys, dict_merge recurses down into dicts nested to an arbitrary depth, updating keys. The merge_dct is merged into dct.- Param:
dct: dict, onto which the merge is executed merge_dct: dict, dct merged into dct
-
satsim.config.
has_key_deep
(d, key)¶ Nested check to see if a dictionary has a key.
- Parameters
d – dict or list
key – str, key name to check for
-
satsim.config.
load_json
(filename)¶ Opens a JSON file and returns the result as a dictionary.
- Parameters
filename – str, path to file
- Returns
A dict, the result.
-
satsim.config.
load_yaml
(filename)¶ Opens a YAML file and returns the result as a dictionary.
- Parameters
filename – str, path to file
- Returns
A dict, the result.
-
satsim.config.
parse_cache
(param)¶ Parse a cache parameter. The input argument, param, may contain the following keys and values which discribe the function to run. For example:
param = { '$cache': './path/to/cache' }
Cache is not used if $cache key is not present.
- Parameters
param – dict, a dictionary that contain keys: $cache
- Returns
- A tuple,
a dictionary, loaded from cache if available a boolean, True if cache loaded, False otherwise
-
satsim.config.
parse_function
(param)¶ Parse a function. The input argument, param, should contain the following keys and values which discribe the function to run. For example:
param = { 'module': 'my_module', 'function': 'my_function', 'kwargs': { 'param_1': 10.0, 'param_2': 'astring' } }
Which is comparable to:
import my_module return lambda: my_function(param_1 = 10.0, param_2 = 'astring')
- Parameters
param – dict, a dictionary that contain keys: module, function, kwargs
- Returns
- A function, a lambda function encapsulating the parsed function and
arguments
-
satsim.config.
parse_function_pipeline
(param)¶ Parse a pipeline of functions. See parse_function.
- Parameters
param – dict, a dictionary that contain keys: module, function, kwargs
- Returns
An func, a function encapsulating the pipeline
-
satsim.config.
parse_generator
(param)¶ Parse and run a generator function. See parse_function.
- Parameters
param – dict, a dictionary that contain keys: module, function, kwargs
- Returns
A dict, a dictionary generated by the generator function
-
satsim.config.
parse_import
(param)¶ Parse a import key. The input argument, param, should contain the following keys and values which discribe the function to run. For example:
param = { '$import': './base.json', 'override': { 'param_1': 10.0, 'param_2': 'override string' } }
- Parameters
param – dict, a dictionary that contain keys: import, and optionally override
- Returns
A dict, a dictionary generated by the generator function
-
satsim.config.
parse_param
(param, dirname=None, run_generator=False, eval_python=False, run_compound=False)¶ Parses a parameter and recursively parses any children parameters.
if the parameter contains the key sample, result from parse_random_sample will be returned.
if the parameter contains the key file, the contents of the loaded pickle file will be returned.
if the parameter contains the key generator, result from parse_generator will be returned.
else if no special keys are found, param is returned.
- Parameters
param – dict, root parameter
dirname – str, root directory for files referenced in param
run_generator – boolean, evaulate generator functions during this pass
- Returns
A any, a random sample, contents of pickle file, or original value
-
satsim.config.
parse_random_sample
(param)¶ Parses a random sample parameter and returns a sample. The value of the key $sample should be the format random.DISTRIBUTION, where DISTRIBUTION is a NumPy random distribution. For example:
p = { "$sample": "random.uniform", "low": 5.0, "high": 22.0 } x = parse_random_sample(p) # x is a value between 5 and 22
If the key $sample is equal to random.choice, one option will be choosen from the key choices. For example:
p = { "$sample": "random.choice", "choices": [1, 2, 4, 8] } x = parse_random_sample(p) # x will be 1, 2, 4, or 8
If the key $sample is equal to random.list, a list of random samples will be generated. For example:
p = { "$sample": "random.list", "length": 5, "value": { "$sample": "random.randint", "low": 0, "high": 10 } } x = parse_random_sample(p) # x will a list of length 5, i.e. x == [7,5,8,5,1]
- Parameters
param – dict, random sample parameter
- Returns
A number, random sample
-
satsim.config.
save_cache
(param, value)¶ Saves a parameter to the disk cache. Parameter will be loaded from cache on any subsequent calls.
- Parameters
param – dict, root parameter to be used as the cache key
value – any, the value to save to cache
-
satsim.config.
save_debug
(configs, output_dir)¶ Writes an array of configs to files for debugging.
- Parameters
configs – array, configuration stages output by transform
output_dir – str, directory to output files
-
satsim.config.
save_json
(filename, config, save_pickle=False)¶ Saves a configuration to a JSON file. Any items that are not JSON serializable are saved to a binary pickle file and saved in the same directory as the file filename.
- Parameters
filename – str, path to file
config – dict, configuration as a dictionary
-
satsim.config.
transform
(config, dirname=None, max_stages=5, with_debug=False, max_imports=20, max_ref=5)¶ Transforms a SatSim configuration, evaluating any random sample parameters, references and/or generator functions. The transformation will happen in two passes. The first pass evaluates sample parameters; the second pass evaluates generator parameters. This is repeated for max_stages or until no more generator or sample keys are found.
- Parameters
config – dict, configuration as a dictionary.
dirname – str, root directory for files referenced in config.
max_stages – int, maximum number of times to evaluate (one stage is equivalent to running pass 1 and pass 2 once each).
with_debug – boolean, return config after each stage.
max_imports – int, maximum number of times to evaluate imports.
max_refs – int, maximum number of times to evaluate refs.
- Returns
- A dict or tuple,
- if with_debug is False:
dict, in place transformation of config
- if with_debug is True:
config: dict, in place transformation of config stages: array, array of dictionaries after each transformation
stage
satsim.satsim module¶
-
satsim.satsim.
gen_images
(ssp, eager=True, output_dir='./', sample_num=0, output_debug=False, queue=None, set_name=None)¶ Generates a single set of images.
Examples:
# load a template json file ssp = load_json('input/config.json') ssp = transform(copy.deepcopy(ssp), 'input/') # generate SatNet files to the output directory gen_images(ssp, eager=True, output_dir='output/')
- Parameters
ssp – dict, static satsim configuration and parameters. Any dynamic parameters should already be transformed.
eager – boolean, Has no effect. True only.
output_dir – str, output directory to save SatNet files.
sample_num – int, recorded to annotation files.
output_debug – boolean, output intermediate debug files.
queue – MultithreadedTaskQueue, if not None, files will be written.
set_name – str, sets the directory name to save the images to, if None, is set to current time.
- Returns
A str, directory to where the output files are saved.
-
satsim.satsim.
gen_multi
(ssp, eager=True, output_dir='./', input_dir='./', device=None, memory=None, pid=0, output_debug=False)¶ Generates multiple sets of images. Number of sets is based on the parameters ssp[‘sim’][‘samples’].
Examples:
# load a template json file ssp = load_json('input/config.json') # edit some parameters ssp['sim']['samples'] = 50 ssp['geometry']['obs']['list']['mv'] = 17.5 # generate SatNet files to the output directory gen_multi(ssp, eager=True, output_dir='output/')
- Parameters
ssp – dict, static or dynamic satsim configuration and parameters.
eager – boolean, Has no effect. True only.
output_dir – str, output directory to save SatNet files.
input_dir – str, typically the input directory of the configuration file.
device – array, array of GPU device IDs to enable. If None, enable all.
pid – int, an ID to associate this instance to.
output_debug – boolean, output intermediate debug files.
-
satsim.satsim.
image_generator
(ssp, output_dir='.', output_debug=False, dir_debug='./Debug', with_meta=False, eager=True, num_sets=0)¶ Generator function for a single set of images.
Examples:
# load a template json file ssp = load_json('input/config.json') ssp = transform(copy.deepcopy(ssp), 'input/') # generate SatNet files to the output directory for results in image_generator(ssp, eager=True, output_dir='output/'): imshow(results.numpy())
- Parameters
ssp – dict, static satsim configuration and parameters. Any dynamic parameters should already be transformed.
output_dir – str, root directory for SatSim configuration file.
sample_num – int, recorded to annotation files.
output_debug – boolean, output intermediate debug files.
dir_debug – str, directory to output debug files.
with_meta – boolean, add metadata to the return function.
eager – boolean, Has no effect. True only.
num_sets – int, number of sets until generator exits. Set to 0 to run forever.
- Returns
fpa_digital: image, rendered image. frame_num: int, frame number. astrometrics: dict, astrometry meta data. obs_os_pix: dict, observations meta data. fpa_conv_star: image, pristine image with stars. fpa_conv_targ: image, pristine image with targets. bg_tf: image, background image. dc_tf: image, dark current image. rn_tf: image, read noise image. num_shot_noise_samples: int, number of shot noise samples averaged
- Return type
An image, the rendered image. If with_meta is set to True, additional values are returned