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:
  • ddict or list

  • keystr, key name to check for

satsim.config.load_json(filename)

Opens a JSON file and returns the result as a dictionary.

Parameters:

filenamestr, 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:

filenamestr, 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 describe the function to run. For example:

param = {
    '$cache': './path/to/cache'
}

Cache is not used if $cache key is not present.

Parameters:

paramdict, 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 describe 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:

paramdict, 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:

paramdict, 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:

paramdict, 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 describe the function to run. For example:

param = {
    '$import': './base.json',
    'override': { 'param_1': 10.0, 'param_2': 'override string' }
}
Parameters:

paramdict, 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:
  • paramdict, root parameter

  • dirnamestr, root directory for files referenced in param

  • run_generatorboolean, evaluate 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 chosen 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:

paramdict, 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:
  • paramdict, root parameter to be used as the cache key

  • valueany, the value to save to cache

satsim.config.save_debug(configs, output_dir)

Writes an array of configs to files for debugging.

Parameters:
  • configsarray, configuration stages output by transform

  • output_dirstr, 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:
  • filenamestr, path to file

  • configdict, 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:
  • configdict, configuration as a dictionary.

  • dirnamestr, root directory for files referenced in config.

  • max_stagesint, maximum number of times to evaluate (one stage is equivalent to running pass 1 and pass 2 once each).

  • with_debugboolean, return config after each stage.

  • max_importsint, maximum number of times to evaluate imports.

  • max_refsint, 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:
  • sspdict, static satsim configuration and parameters. Any dynamic parameters should already be transformed.

  • eagerboolean, Has no effect. True only.

  • output_dirstr, output directory to save SatNet files.

  • sample_numint, recorded to annotation files.

  • output_debugboolean, output intermediate debug files.

  • queueMultithreadedTaskQueue, if not None, files will be written.

  • set_namestr, 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, folder_name=None)

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:
  • sspdict, static or dynamic satsim configuration and parameters.

  • eagerboolean, Has no effect. True only.

  • output_dirstr, output directory to save SatNet files.

  • input_dirstr, typically the input directory of the configuration file.

  • devicearray, array of GPU device IDs to enable. If None, enable all.

  • pidint, an ID to associate this instance to.

  • output_debugboolean, output intermediate debug files.

  • folder_namestr, Optional name for folder to save files to.

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:
  • sspdict, static satsim configuration and parameters. Any dynamic parameters should already be transformed.

  • output_dirstr, root directory for SatSim configuration file.

  • sample_numint, recorded to annotation files.

  • output_debugboolean, output intermediate debug files.

  • dir_debugstr, directory to output debug files.

  • with_metaboolean, add metadata to the return function.

  • eagerboolean, Has no effect. True only.

  • num_setsint, 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