Composites

There are a set of objects in Sympl that wrap multiple components into a single object so they can be called as if they were one component. There is one each for Prognostic, Diagnostic, and Monitor. These can be used to simplify code, so that the way you call a list of components is the same as the way you would call a single component. For example, instead of writing:

prognostic_list = [
    MyPrognostic(),
    MyOtherPrognostic(),
    YetAnotherPrognostic(),
]
all_diagnostics = {}
total_tendencies = {}
for prognostic_component in prognostic_list:
    tendencies, diagnostics = prognostic_component(state)
    # this should actually check to make sure nothing is overwritten,
    # but this code does not
    total_tendencies.update(tendencies)
    for name, value in tendencies.keys():
        if name not in total_tendencies:
            total_tendencies[name] = value
        else:
            total_tendencies[name] += value
    for name, value in diagnostics.items():
        all_diagnostics[name] = value

You could write:

prognostic_composite = PrognosticComposite([
    MyPrognostic(),
    MyOtherPrognostic(),
    YetAnotherPrognostic(),
])
tendencies, diagnostics = prognostic_composite(state)

This second call is much cleaner. It will also automatically detect whether multiple components are trying to write out the same diagnostic, and raise an exception if that is the case (so no results are being silently overwritten). You can get similar simplifications for Diagnostic and Monitor.

Note

PrognosticComposites are mainly useful inside of TimeSteppers, so if you’re only writing a model script it’s unlikely you’ll need them.

API Reference

class sympl.PrognosticComposite(*args)[source]
inputs

tuple of str – The quantities required in the state when the object is called.

tendencies

tuple of str – The quantities for which tendencies are returned when the object is called.

diagnostics

tuple of str – The diagnostic quantities returned when the object is called.

__call__(state)[source]

Gets tendencies and diagnostics from the passed model state.

Parameters:

state (dict) – A model state dictionary.

Returns:

  • tendencies (dict) – A dictionary whose keys are strings indicating state quantities and values are the time derivative of those quantities in units/second at the time of the input state.
  • diagnostics (dict) – A dictionary whose keys are strings indicating state quantities and values are the value of those quantities at the time of the input state.

Raises:
  • SharedKeyError – If multiple Prognostic objects contained in the collection return the same diagnostic quantity.
  • KeyError – If a required quantity is missing from the state.
  • InvalidStateError – If state is not a valid input for a Prognostic instance.
component_class

alias of Prognostic

class sympl.DiagnosticComposite(*args)[source]
inputs

tuple of str – The quantities required in the state when the object is called.

diagnostics

tuple of str – The diagnostic quantities returned when the object is called.

__call__(state)[source]

Gets diagnostics from the passed model state.

Parameters:

state (dict) – A model state dictionary.

Returns:

diagnostics – A dictionary whose keys are strings indicating state quantities and values are the value of those quantities at the time of the input state.

Return type:

dict

Raises:
  • SharedKeyError – If multiple Diagnostic objects contained in the collection return the same diagnostic quantity.
  • KeyError – If a required quantity is missing from the state.
  • InvalidStateError – If state is not a valid input for a Diagnostic instance.
component_class

alias of Diagnostic

class sympl.MonitorComposite(*args)[source]
store(state)[source]

Stores the given state in the Monitor and performs class-specific actions.

Parameters:

state (dict) – A model state dictionary.

Raises:
  • KeyError – If a required quantity is missing from the state.
  • InvalidStateError – If state is not a valid input for a Monitor instance.