Modeling Protocol¶
This module provides some infrastructure that makes it easy to implement abstract “models” to be used within the celerite framework. Many of the methods are probably more generally applicable but the implementation constraints can be simplified since we’re just concerned about supporting the needs of celerite.
The basic premise is that a Model
is an object that has an ordered set
of named parameters. These parameters are assumed to be continuous but they can
have bounds. There is also the concept of an “active set” of parameters that
are being varied in a fit procedure. The other parameters are “frozen” to a
particular value. Frozen parameters can be “thawed” to be returned to the
active set.
There isn’t a formal requirement for the “value” interface that a
Model
subclass should implement but in some cases, a model will be
expected to implement a get_value
method that returns the “value” of the
model (this can mean many different things but we’ll motivate this with an
example below) for the current setting of the parameters.
Since these models will be used in the context of Bayesian parameter estimation
each model also implements a Model.log_prior()
method that computes the
log of the prior probability of the current setting of the model parameters.
The full interface is described in detail below and the tutorials demonstrate the basic usage of the protocol.
-
class
celerite.modeling.
Model
(*args, **kwargs)¶ An abstract class implementing the skeleton of the modeling protocol
Initial parameter values can either be provided as arguments in the same order as
parameter_names
or by name as keyword arguments.A minimal subclass of this would have the form:
class CustomModel(Model): parameter_names = ("parameter_1", "parameter_2") def get_value(self, x): return self.parameter_1 + self.parameter_2 + x model = CustomModel(parameter_1=1.0, parameter_2=2.0) # or... model = CustomModel(1.0, 2.0)
- Parameters
bounds (Optional[list or dict]) – Bounds can be given for each parameter setting their minimum and maximum allowed values. This parameter can either be a
list
(with lengthfull_size
) or adict
with named parameters. Any parameters that are omitted from thedict
will be assumed to have no bounds. These bounds can be retrieved later using thecelerite.Model.get_parameter_bounds()
method and, by default, they are used in thecelerite.Model.log_prior()
method.
-
compute_gradient
(*args, **kwargs)¶ Compute the “gradient” of the model for the current parameters
This method should be overloaded by subclasses to implement the actual functionality of the model. The output of this function should be an array where the first dimension is
full_size
.
-
freeze_all_parameters
()¶ Freeze all parameters of the model
-
freeze_parameter
(name)¶ Freeze a parameter by name
- Parameters
name – The name of the parameter
-
property
full_size
¶ The total number of parameters (including frozen parameters)
-
get_parameter
(name)¶ Get a parameter value by name
- Parameters
name – The name of the parameter
-
get_parameter_bounds
(include_frozen=False)¶ Get a list of the parameter bounds
- Parameters
include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default:
False
)
-
get_parameter_dict
(include_frozen=False)¶ Get an ordered dictionary of the parameters
- Parameters
include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default:
False
)
-
get_parameter_names
(include_frozen=False)¶ Get a list of the parameter names
- Parameters
include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default:
False
)
-
get_parameter_vector
(include_frozen=False)¶ Get an array of the parameter values in the correct order
- Parameters
include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default:
False
)
-
get_value
(*args, **kwargs)¶ Compute the “value” of the model for the current parameters
This method should be overloaded by subclasses to implement the actual functionality of the model.
-
log_prior
()¶ Compute the log prior probability of the current parameters
-
property
parameter_vector
¶ An array of all parameters (including frozen parameters)
-
set_parameter
(name, value)¶ Set a parameter value by name
- Parameters
name – The name of the parameter
value (float) – The new value for the parameter
-
set_parameter_vector
(vector, include_frozen=False)¶ Set the parameter values to the given vector
- Parameters
vector (array[vector_size] or array[full_size]) – The target parameter vector. This must be in the same order as
parameter_names
and it should only include frozen parameters ifinclude_frozen
isTrue
.include_frozen (Optional[bool]) – Should the frozen parameters be included in the returned value? (default:
False
)
-
thaw_all_parameters
()¶ Thaw all parameters of the model
-
thaw_parameter
(name)¶ Thaw a parameter by name
- Parameters
name – The name of the parameter
-
property
vector_size
¶ The number of active (or unfrozen) parameters
-
class
celerite.modeling.
ModelSet
(models)¶ An abstract wrapper for combining named
Model
objectsThe parameter names of a composite model are prepended by the submodel name. For example:
model = ModelSet([ ("model1", Model(par1=1.0, par2=2.0)), ("model2", Model(par3=3.0, par4=4.0)), ]) print(model.get_parameter_names())
will print
["model1:par1", "model1:par2", "model2:par3", "model2:par4"]
- Parameters
models – This should be a list of the form:
[("model1", Model(...)), ("model2", Model(...)), ...]
.
-
freeze_all_parameters
()¶ Freeze all parameters of the model
-
freeze_parameter
(name)¶ Freeze a parameter by name
- Parameters
name – The name of the parameter
-
property
full_size
¶ The total number of parameters (including frozen parameters)
-
get_parameter
(name)¶ Get a parameter value by name
- Parameters
name – The name of the parameter
-
log_prior
()¶ Compute the log prior probability of the current parameters
-
property
parameter_names
¶ tuple() -> empty tuple tuple(iterable) -> tuple initialized from iterable’s items
If the argument is a tuple, the return value is the same object.
-
property
parameter_vector
¶ An array of all parameters (including frozen parameters)
-
set_parameter
(name, value)¶ Set a parameter value by name
- Parameters
name – The name of the parameter
value (float) – The new value for the parameter
-
thaw_all_parameters
()¶ Thaw all parameters of the model
-
thaw_parameter
(name)¶ Thaw a parameter by name
- Parameters
name – The name of the parameter
-
property
vector_size
¶ The number of active (or unfrozen) parameters
-
class
celerite.modeling.
ConstantModel
(*args, **kwargs)¶ A simple concrete model with a single parameter
value
- Parameters
value (float) – The value of the model.
-
compute_gradient
(x)¶ Compute the “gradient” of the model for the current parameters
This method should be overloaded by subclasses to implement the actual functionality of the model. The output of this function should be an array where the first dimension is
full_size
.
-
get_value
(x)¶ Compute the “value” of the model for the current parameters
This method should be overloaded by subclasses to implement the actual functionality of the model.