Roles

In some situations (particularly when dealing with multiple related models) it can be advantageous to access model parameters and data via roles. These are special references that are able to pull values from models, or assume default values, without actually changing the models.

Parameter References

class larch.roles.ParameterRef(name, default=None, fmt=None)

An abstract reference to a parameter, which may or may not be included in any given model.

Parameters:
  • name (str) – The name of the parameter to reference.
  • default (numeric or None) – When a targeted model does not include the referenced parameter, use this value for value() and str(). If given as None, those methods will raise an exception.
  • fmt (str or None) – The format string to use for str().

For convenience, ParameterRef is aliased as P in the roles module. After a ParameterRef object is created, its attributes can be modified using these methods:

ParameterRef.name(n)

Set or re-set the name of the parameter referenced.

Parameters:n (str) – The new name of the parameter.
Returns:This method returns the self object, to facilitate method chaining.
Return type:ParameterRef
ParameterRef.default_value(val)

Set or re-set the default value.

Parameters:val (numeric or None) – The new default value. This will be used by value() when the parameter is not included in the targeted model. Set to None to raise an exception instead.
Returns:This method returns the self object, to facilitate method chaining.
Return type:ParameterRef
ParameterRef.fmt(format)

Set or re-set the format string for the parameter referenced.

Parameters:format (str) – The new format string. This will be used to format the parameter value when calling str().
Returns:This method returns the self object, to facilitate method chaining.
Return type:ParameterRef

You can access a referenced parameter from a model using these methods:

ParameterRef.value(m)

The value of the parameter in a given model.

Parameters:m (Model) – The model from which to extract a parameter value.
Raises:LarchError – When the model does not contain a parameter with the same name as this ParameterRef, and the default_value for this ParameterRef is None.
ParameterRef.valid(m)

Check if this ParameterRef would give a value for a given model.

Parameters:m (Model) – The model from which to extract a parameter value.
Returns:False if the value method would raise an exception, and True otherwise.
Return type:bool
ParameterRef.strf(m, fmt=None)

Gives the value() of the parameter in a given model as a string.

The string is formated using the fmt() string if given. If not given, Python’s default string formatting is used.

Parameters:
  • m (Model) – The model from which to extract a parameter value.
  • fmt (str or None) – If not None, a format string which will be used, overriding any previous setting by a fmt() command. The override is valid for this method call only, and does not change the format for future calls.
Raises:

KeyError – When the model does not contain a parameter with the same name as this ParameterRef, and the default_value for this ParameterRef is None.

Math using Parameter References

You can do some simple math with ParameterRef objects. Currently supported are addition, subtraction, multiplication, and division. This allows, for example, the automatic calculation of values of time for a model:

>>> m = larch.Model.Example(1, pre=True)
>>> from larch.roles import P
>>> VoT_cents_per_minute = P.tottime / P.totcost
>>> VoT_cents_per_minute.value(m)
10.434...
>>> print("The implied value of time is", VoT_cents_per_minute.strf(m, fmt="{:.1f}¢/minute"))
The implied value of time is 10.4¢/minute
>>> VoT_dollars_per_hour = (P.tottime * 60) / (P.totcost * 100)
>>> print("The implied value of time is", VoT_dollars_per_hour.strf(m, fmt="${:.2f}/hr"))
The implied value of time is $6.26/hr

Data References

class larch.roles.DataRef(name, descrip=None)