satsim package — SatSim 0.12.0 documentation

# satsim package

Top-level package for SatSim.

## Subpackages

- satsim.dataset package
  - Submodules
  - satsim.dataset.augment module
- satsim.generator package
  - Subpackages
    - satsim.generator.obs package
      - Submodules
      - satsim.generator.obs.breakup module
      - satsim.generator.obs.cso module
      - satsim.generator.obs.geometry module
      - satsim.generator.obs.io module
      - satsim.generator.obs.rpo module
- satsim.geometry package
  - Submodules
  - satsim.geometry.astrometric module
  - satsim.geometry.draw module
  - satsim.geometry.random module
  - satsim.geometry.sgp4 module
  - satsim.geometry.sprite module
  - satsim.geometry.sstr7 module
  - satsim.geometry.transform module
  - satsim.geometry.twobody module
  - satsim.geometry.wcs module
- satsim.image package
  - Submodules
  - satsim.image.augment module
  - satsim.image.fpa module
  - satsim.image.model module
  - satsim.image.noise module
  - satsim.image.psf module
  - satsim.image.render module
- satsim.io package
  - Submodules
  - satsim.io.fits module
  - satsim.io.image module
  - satsim.io.satnet module
- satsim.math package
  - Submodules
  - satsim.math.angle module
  - satsim.math.conv module
  - satsim.math.fft module
  - satsim.math.random module
  - satsim.math.stats module
- satsim.pipeline package
- satsim.time package
- satsim.util package
  - Submodules
  - satsim.util.system module
  - satsim.util.thread module
  - satsim.util.timer module

## 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