Skip to main content
`Ctrl`+`K`

# Model

class astropy.modeling.Model(*args, meta=None, name=None, **kwargs)

  Bases: `object`

  Base class for all models.

  This is an abstract class and should not be instantiated directly.

  The following initialization arguments apply to the majority of Model subclasses by default (exceptions include specialized utility models like `Mapping`). Parametric models take all their parameters as arguments, followed by any of the following optional keyword arguments:

  Parameters:
    name `python:str`, optional

      A human-friendly name associated with this model instance (particularly useful for identifying the individual components of a compound model).

    meta `python:dict`, optional

      An optional dict of user-defined metadata to attach to this model. How this is used and interpreted is up to the user or individual use case.

    n_models `python:int`, optional

      If given an integer greater than 1, a model set is instantiated instead of a single model. This affects how the parameter arguments are interpreted. In this case each parameter must be given as a list or array–elements of this array are taken along the first axis (or `model_set_axis` if specified), such that the Nth element is the value of that parameter for the Nth model in the set.

      See the section on model sets in the documentation for more details.

    model_set_axis `python:int`, optional

      This argument only applies when creating a model set (i.e. `n_models > 1`). It changes how parameter values are interpreted. Normally the first axis of each input parameter array (properly the 0th axis) is taken as the axis corresponding to the model sets. However, any axis of an input array may be taken as this “model set axis”. This accepts negative integers as well–for example use `model_set_axis=-1` if the last (most rapidly changing) axis should be associated with the model sets. Also, `model_set_axis=False` can be used to tell that a given input should be used to evaluate all the models in the model set.

    fixed `python:dict`, optional

      Dictionary `{parameter_name: bool}` setting the fixed constraint for one or more parameters. `True` means the parameter is held fixed during fitting and is prevented from updates once an instance of the model has been created.

      Alternatively the `fixed` property of a parameter may be used to lock or unlock individual parameters.

    tied `python:dict`, optional

      Dictionary `{parameter_name: callable}` of parameters which are linked to some other parameter. The dictionary values are callables providing the linking relationship.

      Alternatively the `tied` property of a parameter may be used to set the `tied` constraint on individual parameters.

    bounds `python:dict`, optional

      A dictionary `{parameter_name: value}` of lower and upper bounds of parameters. Keys are parameter names. Values are a list or a tuple of length 2 giving the desired range for the parameter.

      Alternatively the `min` and `max` or ~astropy.modeling.Parameter.bounds` properties of a parameter may be used to set bounds on individual parameters.

    eqcons `python:list`, optional

      List of functions of length n such that `eqcons[j](x0, *args) == 0.0` in a successfully optimized problem.

    ineqcons `python:list`, optional

      List of functions of length n such that `ieqcons[j](x0, *args) >= 0.0` is a successfully optimized problem.

  Examples

      >>> from astropy.modeling import models
      >>> def tie_center(model):
      ...         mean = 50 * model.stddev
      ...         return mean
      >>> tied_parameters = {'mean': tie_center}

  Specify that `'mean'` is a tied parameter in one of two ways:

      >>> g1 = models.Gaussian1D(amplitude=10, mean=5, stddev=.3,
      ...                        tied=tied_parameters)

  or

      >>> g1 = models.Gaussian1D(amplitude=10, mean=5, stddev=.3)
      >>> g1.mean.tied
      False
      >>> g1.mean.tied = tie_center
      >>> g1.mean.tied
      <function tie_center at 0x...>

  Fixed parameters:

      >>> g1 = models.Gaussian1D(amplitude=10, mean=5, stddev=.3,
      ...                        fixed={'stddev': True})
      >>> g1.stddev.fixed
      True

  or

      >>> g1 = models.Gaussian1D(amplitude=10, mean=5, stddev=.3)
      >>> g1.stddev.fixed
      False
      >>> g1.stddev.fixed = True
      >>> g1.stddev.fixed
      True

  Attributes Summary

  `bbox_with_units` |
  `bounding_box` | A `tuple` of length `n_inputs` defining the bounding box limits, or raise `NotImplementedError` for no bounding_box.
  `bounds` | A `dict` mapping parameter names to their upper and lower bounds as `(min, max)` tuples or `[min, max]` lists.
  `cov_matrix` | Fitter should set covariance matrix, if available.
  `eqcons` | List of parameter equality constraints.
  `fittable` |
  `fixed` | A `dict` mapping parameter names to their fixed constraint.
  `has_bounds` | Whether the model has any bounds constraints.
  `has_fixed` | Whether the model has any fixed constraints.
  `has_tied` | Whether the model has any tied constraints.
  `has_user_bounding_box` | A flag indicating whether or not a custom bounding_box has been assigned to this model by a user, via assignment to `model.bounding_box`.
  `has_user_inverse` | A flag indicating whether or not a custom inverse model has been assigned to this model by a user, via assignment to `model.inverse`.
  `ineqcons` | List of parameter inequality constraints.
  `input_units` | This property is used to indicate what units or sets of units the evaluate method expects, and returns a dictionary mapping inputs to units (or `None` if any units are accepted).
  `input_units_allow_dimensionless` | Allow dimensionless input (and corresponding output).
  `input_units_equivalencies` |
  `input_units_strict` | Enforce strict units on inputs to evaluate.
  `inputs` |
  `inverse` | Returns a new `Model` instance which performs the inverse transform, if an analytic inverse is defined for this model.
  `linear` |
  `meta` | A dict-like object to store optional information.
  `model_constraints` | Primarily for informational purposes, these are the types of constraints that constrain model evaluation.
  `model_set_axis` | The index of the model set axis--that is the axis of a parameter array that pertains to which model a parameter value pertains to--as specified when the model was initialized.
  `n_inputs` | The number of inputs.
  `n_outputs` | The number of outputs.
  `n_submodels` | Return the number of components in a single model, which is obviously 1.
  `name` | User-provided name for this model instance.
  `outputs` |
  `param_names` | Names of the parameters that describe models of this type.
  `param_sets` | Return parameters as a pset.
  `parameter_constraints` | Primarily for informational purposes, these are the types of constraints that can be set on a model's parameters.
  `parameters` | A flattened array of all parameter values in all parameter sets.
  `return_units` | This property is used to indicate what units or sets of units the output of evaluate should be in, and returns a dictionary mapping outputs to units (or `None` if any units are accepted).
  `separable` | A flag indicating whether a model is separable.
  `standard_broadcasting` |
  `stds` | Standard deviation of parameters, if covariance matrix is available.
  `sync_constraints` | This is a boolean property that indicates whether or not accessing constraints automatically check the constituent models current values.
  `tied` | A `dict` mapping parameter names to their tied constraint.
  `uses_quantity` | True if this model has been created with `Quantity` objects or if there are no parameters.

  Methods Summary

  `__call__`(*args, **kwargs) | Evaluate this model using the given input(s) and the parameter values that were specified when the model was instantiated.
  `coerce_units`([input_units, return_units, ...]) | Attach units to this (unitless) model.
  `copy`() | Return a copy of this model.
  `deepcopy`() | Return a deep copy of this model.
  `evaluate`(*args, **kwargs) | Evaluate the model on some input variables.
  `get_bounding_box`([with_bbox]) | Return the `bounding_box` of a model if it exists or `None` otherwise.
  `has_inverse`() | Returns True if the model has an analytic or user inverse defined.
  `input_shape`(inputs) | Get input shape for bounding_box evaluation.
  `output_units`(**kwargs) | Return a dictionary of output units for this model given a dictionary of fitting inputs and outputs.
  `prepare_inputs`(*inputs[, model_set_axis, ...]) | This method is used in `__call__` to ensure that all the inputs to the model can be broadcast into compatible shapes (if one or both of them are input as arrays), particularly if there are more than one parameter sets.
  `prepare_outputs`(broadcasted_shapes, ...) |
  `rename`([name, inputs, outputs]) | Return a copy of this model with a new name.
  `render`([out, coords]) | Evaluate a model at fixed positions, respecting the `bounding_box`.
  `set_slice_args`(*args) |
  `strip_units_from_tree`() |
  `sum_of_implicit_terms`(*args, **kwargs) | Evaluate the sum of any implicit model terms on some input variables.
  `with_units_from_data`(**kwargs) | Return an instance of the model which has units for which the parameter values are compatible with the data units specified.
  `without_units_for_data`(**kwargs) | Return an instance of the model for which the parameter values have been converted to the right units for the data, then the units have been stripped away.

  Attributes Documentation

  bbox_with_units
  bounding_box

    A `tuple` of length `n_inputs` defining the bounding box limits, or raise `NotImplementedError` for no bounding_box.

    The default limits are given by a `bounding_box` property or method defined in the class body of a specific model. If not defined then this property just raises `NotImplementedError` by default (but may be assigned a custom value by a user). `bounding_box` can be set manually to an array-like object of shape `(model.n_inputs, 2)`. For further usage, see Efficient Model Rendering with Bounding Boxes

    The limits are ordered according to the `numpy` `'C'` indexing convention, and are the reverse of the model input order, e.g. for inputs `('x', 'y', 'z')`, `bounding_box` is defined:

    - for 1D: `(x_low, x_high)`

    - for 2D: `((y_low, y_high), (x_low, x_high))`

    - for 3D: `((z_low, z_high), (y_low, y_high), (x_low, x_high))`

    Examples

    Setting the `bounding_box` limits for a 1D and 2D model:

        >>> from astropy.modeling.models import Gaussian1D, Gaussian2D
        >>> model_1d = Gaussian1D()
        >>> model_2d = Gaussian2D(x_stddev=1, y_stddev=1)
        >>> model_1d.bounding_box = (-5, 5)
        >>> model_2d.bounding_box = ((-6, 6), (-5, 5))

    Setting the bounding_box limits for a user-defined 3D `custom_model`:

        >>> from astropy.modeling.models import custom_model
        >>> def const3d(x, y, z, amp=1):
        ...    return amp
        ...
        >>> Const3D = custom_model(const3d)
        >>> model_3d = Const3D()
        >>> model_3d.bounding_box = ((-6, 6), (-5, 5), (-4, 4))

    To reset `bounding_box` to its default limits just delete the user-defined value–this will reset it back to the default defined on the class:

        >>> del model_1d.bounding_box

    To disable the bounding box entirely (including the default), set `bounding_box` to `None`:

        >>> model_1d.bounding_box = None
        >>> model_1d.bounding_box
        Traceback (most recent call last):
        NotImplementedError: No bounding box is defined for this model
        (note: the bounding box was explicitly disabled for this model;
        use `del model.bounding_box` to restore the default bounding box,
        if one is defined for this model).

  bounds

    A `dict` mapping parameter names to their upper and lower bounds as `(min, max)` tuples or `[min, max]` lists.

  cov_matrix

    Fitter should set covariance matrix, if available.

  eqcons

    List of parameter equality constraints.

  fittable = False
  fixed

    A `dict` mapping parameter names to their fixed constraint.

  has_bounds

    Whether the model has any bounds constraints.

  has_fixed

    Whether the model has any fixed constraints.

  has_tied

    Whether the model has any tied constraints.

  has_user_bounding_box

    A flag indicating whether or not a custom bounding_box has been assigned to this model by a user, via assignment to `model.bounding_box`.

  has_user_inverse

    A flag indicating whether or not a custom inverse model has been assigned to this model by a user, via assignment to `model.inverse`.

  ineqcons

    List of parameter inequality constraints.

  input_units

    This property is used to indicate what units or sets of units the evaluate method expects, and returns a dictionary mapping inputs to units (or `None` if any units are accepted).

    Model sub-classes can also use function annotations in evaluate to indicate valid input units, in which case this property should not be overridden since it will return the input units based on the annotations.

  input_units_allow_dimensionless

    Allow dimensionless input (and corresponding output). If this is True, input values to evaluate will gain the units specified in input_units. If this is a dictionary then it should map input name to a bool to allow dimensionless numbers for that input. Only has an effect if input_units is defined.

  input_units_equivalencies = None
  input_units_strict

    Enforce strict units on inputs to evaluate. If this is set to True, input values to evaluate will be in the exact units specified by input_units. If the input quantities are convertible to input_units, they are converted. If this is a dictionary then it should map input name to a bool to set strict input units for that parameter.

  inputs
  inverse

    Returns a new `Model` instance which performs the inverse transform, if an analytic inverse is defined for this model.

    Even on models that don’t have an inverse defined, this property can be set with a manually-defined inverse, such a pre-computed or experimentally determined inverse (often given as a `PolynomialModel`, but not by requirement).

    A custom inverse can be deleted with `del model.inverse`. In this case the model’s inverse is reset to its default, if a default exists (otherwise the default is to raise `NotImplementedError`).

    Note to authors of `Model` subclasses: To define an inverse for a model simply override this property to return the appropriate model representing the inverse. The machinery that will make the inverse manually-overridable is added automatically by the base class.

  linear = True
  meta = None

    A dict-like object to store optional information.

  model_constraints = ('eqcons', 'ineqcons')

    Primarily for informational purposes, these are the types of constraints that constrain model evaluation.

  model_set_axis

    The index of the model set axis–that is the axis of a parameter array that pertains to which model a parameter value pertains to–as specified when the model was initialized.

    See the documentation on Model Sets for more details.

  n_inputs

    The number of inputs.

  n_outputs

    The number of outputs.

  n_submodels

    Return the number of components in a single model, which is obviously 1.

  name

    User-provided name for this model instance.

  outputs
  param_names = ()

    Names of the parameters that describe models of this type.

    The parameters in this tuple are in the same order they should be passed in when initializing a model of a specific type. Some types of models, such as polynomial models, have a different number of parameters depending on some other property of the model, such as the degree.

    When defining a custom model class the value of this attribute is automatically set by the `Parameter` attributes defined in the class body.

  param_sets

    Return parameters as a pset.

    This is a list with one item per parameter set, which is an array of that parameter’s values across all parameter sets, with the last axis associated with the parameter set.

  parameter_constraints = ('fixed', 'tied', 'bounds')

    Primarily for informational purposes, these are the types of constraints that can be set on a model’s parameters.

  parameters

    A flattened array of all parameter values in all parameter sets.

    Fittable parameters maintain this list and fitters modify it.

  return_units

    This property is used to indicate what units or sets of units the output of evaluate should be in, and returns a dictionary mapping outputs to units (or `None` if any units are accepted).

    Model sub-classes can also use function annotations in evaluate to indicate valid output units, in which case this property should not be overridden since it will return the return units based on the annotations.

  separable

    A flag indicating whether a model is separable.

  standard_broadcasting = True
  stds

    Standard deviation of parameters, if covariance matrix is available.

  sync_constraints

    This is a boolean property that indicates whether or not accessing constraints automatically check the constituent models current values. It defaults to True on creation of a model, but for fitting purposes it should be set to False for performance reasons.

  tied

    A `dict` mapping parameter names to their tied constraint.

  uses_quantity

    True if this model has been created with `Quantity` objects or if there are no parameters.

    This can be used to determine if this model should be evaluated with `Quantity` or regular floats.

  Methods Documentation

  __call__(*args, **kwargs)

    Evaluate this model using the given input(s) and the parameter values that were specified when the model was instantiated.

  coerce_units(input_units=None, return_units=None, input_units_equivalencies=None, input_units_allow_dimensionless=False)

    Attach units to this (unitless) model.

    Parameters:
      input_units `python:dict` or `python:tuple`, optional

        Input units to attach. If dict, each key is the name of a model input, and the value is the unit to attach. If tuple, the elements are units to attach in order corresponding to `inputs`.

      return_units `python:dict` or `python:tuple`, optional

        Output units to attach. If dict, each key is the name of a model output, and the value is the unit to attach. If tuple, the elements are units to attach in order corresponding to `outputs`.

      input_units_equivalencies `python:dict`, optional

        Default equivalencies to apply to input values. If set, this should be a dictionary where each key is a string that corresponds to one of the model inputs.

      input_units_allow_dimensionless bool or `python:dict`, optional

        Allow dimensionless input. If this is True, input values to evaluate will gain the units specified in input_units. If this is a dictionary then it should map input name to a bool to allow dimensionless numbers for that input.

    Returns:
      `CompoundModel`

        A `CompoundModel` composed of the current model plus `UnitsMapping` model(s) that attach the units.

    Raises:
      `ValueError`

        If the current model already has units.

    Examples

    Wrapping a unitless model to require and convert units:

        >>> from astropy.modeling.models import Polynomial1D
        >>> from astropy import units as u
        >>> poly = Polynomial1D(1, c0=1, c1=2)
        >>> model = poly.coerce_units((u.m,), (u.s,))
        >>> model(u.Quantity(10, u.m))
        <Quantity 21. s>
        >>> model(u.Quantity(1000, u.cm))
        <Quantity 21. s>
        >>> model(u.Quantity(10, u.cm))
        <Quantity 1.2 s>

    Wrapping a unitless model but still permitting unitless input:

        >>> from astropy.modeling.models import Polynomial1D
        >>> from astropy import units as u
        >>> poly = Polynomial1D(1, c0=1, c1=2)
        >>> model = poly.coerce_units((u.m,), (u.s,), input_units_allow_dimensionless=True)
        >>> model(u.Quantity(10, u.m))
        <Quantity 21. s>
        >>> model(10)
        <Quantity 21. s>

  copy()

    Return a copy of this model.

    Uses a deep copy so that all model attributes, including parameter values, are copied as well.

  deepcopy()

    Return a deep copy of this model.

  abstractmethod evaluate(*args, **kwargs)

    Evaluate the model on some input variables.

  get_bounding_box(with_bbox=True)

    Return the `bounding_box` of a model if it exists or `None` otherwise.

    Parameters:
      with_bbox

        The value of the `with_bounding_box` keyword argument when calling the model. Default is `True` for usage when looking up the model’s `bounding_box` without risk of error.

  has_inverse()

    Returns True if the model has an analytic or user inverse defined.

  input_shape(inputs)

    Get input shape for bounding_box evaluation.

  output_units(**kwargs)

    Return a dictionary of output units for this model given a dictionary of fitting inputs and outputs.

    The input and output Quantity objects should be given as keyword arguments.

    Notes

    This method is needed in order to be able to fit models with units in the parameters, since we need to temporarily strip away the units from the model during the fitting (which might be done by e.g. scipy functions).

    This method will force extra model evaluations, which maybe computationally expensive. To avoid this, one can add a return_units property to the model, see return_units.

  prepare_inputs(*inputs, model_set_axis=None, equivalencies=None, **kwargs)

    This method is used in `__call__` to ensure that all the inputs to the model can be broadcast into compatible shapes (if one or both of them are input as arrays), particularly if there are more than one parameter sets. This also makes sure that (if applicable) the units of the input will be compatible with the evaluate method.

  prepare_outputs(broadcasted_shapes, *outputs, **kwargs)
  classmethod rename(name=None, inputs=None, outputs=None)

    Return a copy of this model with a new name.

  render(out=None, coords=None)

    Evaluate a model at fixed positions, respecting the `bounding_box`.

    The key difference relative to evaluating the model directly is that this method is limited to a bounding box if the `bounding_box` attribute is set.

    Parameters:
      out `numpy.ndarray`, optional

        An array that the evaluated model will be added to. If this is not given (or given as `None`), a new array will be created.

      coords numpy:array_like, optional

        An array to be used to translate from the model’s input coordinates to the `out` array. It should have the property that `self(coords)` yields the same shape as `out`. If `out` is not specified, `coords` will be used to determine the shape of the returned array. If this is not provided (or None), the model will be evaluated on a grid determined by `bounding_box`.

    Returns:
      out `numpy.ndarray`

        The model added to `out` if `out` is not `None`, or else a new array from evaluating the model over `coords`. If `out` and `coords` are both `None`, the returned array is limited to the `bounding_box` limits. If `bounding_box` is `None`, `arr` or `coords` must be passed.

    Raises:
      `ValueError`

        If `coords` are not given and the `bounding_box` of this model is not set.

    Examples

    Efficient Model Rendering with Bounding Boxes

  set_slice_args(*args)
  strip_units_from_tree()
  sum_of_implicit_terms(*args, **kwargs)

    Evaluate the sum of any implicit model terms on some input variables. This includes any fixed terms used in evaluating a linear model that do not have corresponding parameters exposed to the user. The prototypical case is `astropy.modeling.functional_models.Shift`, which corresponds to a function y = a + bx, where b=1 is intrinsically fixed by the type of model, such that sum_of_implicit_terms(x) == x. This method is needed by linear fitters to correct the dependent variable for the implicit term(s) when solving for the remaining terms (ie. a = y - bx).

  with_units_from_data(**kwargs)

    Return an instance of the model which has units for which the parameter values are compatible with the data units specified.

    The input and output Quantity objects should be given as keyword arguments.

    Notes

    This method is needed in order to be able to fit models with units in the parameters, since we need to temporarily strip away the units from the model during the fitting (which might be done by e.g. scipy functions).

    The units that the parameters will gain are not necessarily the units of the input data, but are derived from them. Model subclasses that want fitting to work in the presence of quantities need to define a `_parameter_units_for_data_units` method that takes the input and output units (as two dictionaries) and returns a dictionary giving the target units for each parameter.

  without_units_for_data(**kwargs)

    Return an instance of the model for which the parameter values have been converted to the right units for the data, then the units have been stripped away.

    The input and output Quantity objects should be given as keyword arguments.

    Notes

    This method is needed in order to be able to fit models with units in the parameters, since we need to temporarily strip away the units from the model during the fitting (which might be done by e.g. scipy functions).

    The units that the parameters should be converted to are not necessarily the units of the input data, but are derived from them. Model subclasses that want fitting to work in the presence of quantities need to define a `_parameter_units_for_data_units` method that takes the input and output units (as two dictionaries) and returns a dictionary giving the target units for each parameter.