Flags and refusals#

A result with an accuracy warning is returned with an AccuracyWarning, and the result’s validation report has the tier "warned". A refusal is an error that the package raises instead of returning a result. The message of each error states the cause, and each section below gives the exception class.

The distribution function is always returned#

compute_df returns the distribution function of every component for which the inversion is defined, whatever the sign of the distribution function. The result states where the distribution function is negative. The result also states the energy at which the distribution function crosses zero, the distribution function’s minimum, and k_t_min, the lowest truncation energy that gives a valid equilibrium.

A model is always a valid equilibrium#

truncate and solve return a Model only where one exists. A request with no physical equilibrium raises UnphysicalModelError. The exception’s result attribute holds the distribution function, or the model without an edge where the truncation gives no edge, so the distribution function need not be recomputed. A Method II Component takes the truncated density of a Method I model. A Method II Component whose central anisotropy \(\beta_{\rm c}\) violates the existence condition at the edge of that truncated density raises UnphysicalModelError when the Component is created. The message states the bound that \(\beta_{\rm c}\) must exceed.

A model that is not spatially finite is a model#

An untruncated model, which truncate and solve return without a Truncation, has a density that does not reach zero at a finite radius. Such a model is returned with spatially_finite false, an infinite r_t and a finite total mass mass_t. A truncation whose model has no edge raises UnphysicalModelError, and so does an untruncated model whose total mass diverges. A model that is not spatially finite raises no error and issues no AccuracyWarning for that property. The calls that need a spatially finite model act as follows:

  • a Truncation by target mass or target radius that no spatially finite model reaches raises UnphysicalModelError, whose message states the value reached at the limit of the search;

  • sampling requires an explicit sampling radius, and records the mass inside it;

  • an observable at a projected radius beyond the outermost projected radius of the model’s line-of-sight table raises InputError, and the message states the radius that bounds the table.

A distribution function that diverges at the truncation energy#

A Method II model whose central anisotropy \(\beta_{\rm c}\) lies more than 1 below the \(\beta_{\rm c}\) of the Method I model whose truncated density the Method II model uses has a distribution function that diverges, integrably, at the truncation energy. The package returns the Method II model and writes a warning to the package’s log. The warning gives the exponent and says the model is a valid equilibrium of finite density whose stability is not established.

One component#

In ver. 1.0.0, compute_df and solve take one Component and raise InputError for a sequence of more than one Component. A model of several components comes only from superpose, which combines models that share one truncated density and potential. Several components with different density profiles in one potential, and tracer populations in a fixed potential, are on the Upcoming features page.

The attributes to read first in a result#

  • validation: the report and its tier;

  • spatially_finite;

  • r_t and mass_t: the model’s outer radius and total mass, in the model’s unit system;

  • identity: what the result was computed from;

  • units: the unit system in which the result is presented;

  • timing: the wall-clock time of each step of the computation, in seconds;

  • in a file that write produces, the hardware (CPU or GPU) and the software versions of the session that wrote the file.