Smart Defaults

Smart defaults are functions whose return values depend on the values of other model attributes. The SmartDefault class stores information required to run a “smart default” function.

Since smart defaults depend on attributes which may themselves have smart defaults, the functions must be evaluated in the correct order. A directed graph is created representing the set of smart defaults and their dependencies. The graph is sorted topologically to produce the proper run order. The functions are then invoked in sequence when a Field is run, after calling the field.reset(), and just before running the field’s processes.

Smart default functions are defined using a decorator:

@SmartDefault.register("Analysis.attr_name", ["dep1", "dep2"])
  def my_func(arg1, arg2)
    return do_something(arg1, arg1)

The arguments are the name of the attribute that is computed by the function, and a list of attributes on which the function depends. The values of the attributes are acquired from the corresponding object and passed to the function following the decorator. In the example above, the values of “dep1” and “dep2” are passed to the function my_func as arguments arg1 and arg2. The function should return the value to set the named attribute to.

The names of the target attribute and the dependencies can be simple attribute names, or a class or process name can be specified using dot notation, e.g., “Field.my_attribute” to identify the location of the attribute.

If the class or process specifier is absent, the default attribute location differs depending on whether the wrapped function is a method or a regular function. If it is a method, a missing location specifier defaults to the name of the class defining the method. If the wrapped function is a regular (non-method) function, the location specifier defaults to “Field”.

exception opgee.smart_defaults.ProcessNotFoundError

Raised when an attribute of a named Process is unavailable for Smart Default processing because the Process doesn’t exist in the Field under evaluation.

class opgee.smart_defaults.SmartDefault(attr_name, wrapper, user_func, dependencies)

Create a SmartDefault instance. Do not use this method directly: use the opgee.smart_defaults.SmartDefault.register decorator instead. The decorator can be used both on methods of OPGEE classes and on ordinary functions.

Attribute names can be of the form class_name.attr_name or attr_name. If the class_name is “Field” or “Analysis”, the current Field or Analysis instance, respectively, is assumed to hold attr_name. Class names other than “Field” or “Analysis” are interpreted as OPGEE Process names in the current Field.

If a class_name is not specified, the default class name is “Field” for ordinary functions. For methods, the default class name is that of class defining the method.

If a SmartDefault is defined for a Process that is not included in the current Field, a warning is issued and the smart default is ignored.

Parameters:

  • attr_name – (str) the attribute name

  • wrapper – (callable) the wrapper produced by the decorator

  • user_func – (callable) the wrapped function

  • dependencies – (list of str) names of attributes on which attr_name depends.

classmethod apply_defaults(field, analysis=None)

Apply all SmartDefaults for the given analysis and field objects, in dependency order.

Parameters:

  • field – (opgee.Field) The field being run.

  • analysis – (opgee.Analysis) The analysis being run.

Returns:

none

find_attr(attr_name, analysis, field)

Find an attribute in the Analysis, Field, or in a named Process.

Parameters:

  • attr_name – (str) a simple attribute name or a dot-delimited name of the form “class_name.attr_name”.

  • analysis – (opgee.Analysis) the Analysis being run.

  • field – (opgee.Field) the Field being run.

  • raise_error – (bool) whether to raise an error

Returns:

(tuple of (opgee.AttributeMixin, opgee.Attribute)) the object containing the Attribute object, and the Attribute object itself. If a specified process is not found and raise_error is False, the tuple (None, None) is returned.

Raises:

  • OpgeeException – if the attribute is not found

  • ProcessNotFound – if the process specified as containing an attribute is not found.

classmethod register(attr_name, dependencies)

The @register decorator function. Users can wrap methods or regular functions.

Parameters:

  • attr_name – (str) The name of an attribute, with or without a class or Process name specifier.

  • dependencies – (list of str) The names of attributes on which attr_name depends. These follow the same rules for class or Process specifier defined above.

Returns:

(function) The decorator function.

classmethod run_order()

Create a directed graph of the dependencies among attributes and return the list of dependencies in topologically-sorted order. The result is cached since for any set of code, the smart default dependency network is fixed.

Returns:

(list of SmartDefault instances) in dependency order