autofit.Analysis

class autofit.Analysis(use_jax: bool = False, use_jax_for_visualization: bool = False, **kwargs)

Bases: ABC

Protocol for an analysis. Defines methods that can or must be implemented to define a class that compute the likelihood that some instance fits some data.

Methods

compute_latent_samples	Compute latent variables from a model instance.
compute_latent_variables	Override to compute latent variables from the instance.
fit_for_visualization	Build the fit used by the visualizer.
log_likelihood_function
make_result	Returns the Result of the non-linear search after it is completed.
modify_after_fit	Overwrite this method to modify the attributes of the Analysis class before the non-linear search begins.
modify_before_fit	Overwrite this method to modify the attributes of the Analysis class before the non-linear search begins.
modify_model
perform_quick_update
print_vram_use	Print JAX VRAM use for a given batch size.
save_attributes
save_results
save_results_combined
with_model	Associate an explicit model with this analysis.

Attributes

LATENT_KEYS
supports_background_update	Whether this analysis supports background quick updates.
supports_jax_visualization	Whether the visualizer can work directly with JAX arrays.

class Result(samples_summary: SamplesSummary, paths: AbstractPaths | None = None, samples: Samples | None = None, search_internal: object | None = None, analysis: Analysis | None = None)

Bases: AbstractResult

The result of a non-linear search.

The default behaviour is for all key results to be in the samples_summary attribute, which is a concise summary of the results of the non-linear search. The reasons for this to be the main attribute are:

• It is concise and therefore has minimal I/O overhead, which is important because when runs are resumed

the results are loaded often, which can become very slow for large results via a samples.csv.

• The output.yaml config files can be used to disable the output of the samples.csv file

and search_internal.dill files. This means in order for results to be loaded in a way that allows a run to resume, the samples_summary must contain all results necessary to resume the run.

For this reason, the samples and search_internal attributes are optional. On the first run of a model-fit, they will always contain values as they are passed in via memory from the results of the search. However, if a run is resumed they are no longer available in memory, and they will only be available if their corresponding samples.csv and search_internal.dill files are output on disk and available to load.

This object includes:

• The samples_summary attribute, which is a summary of the results of the non-linear search.

• The paths attribute, which contains the path structure to the results of the search on the hard-disk and

is used to load the samples and search internal attributes if they are required and not available in memory.

• The samples of the non-linear search (E.g. MCMC chains, nested sampling samples) which are used to compute

the maximum likelihood model, posteriors and other properties.

• The non-linear search used to perform the model fit in its internal format (e.g. the Dynesty sampler used

by dynesty itself as opposed to PyAutoFit abstract classes).

Parameters:

• samples_summary – A summary of the most important samples of the non-linear search (e.g. maximum log likelihood, median PDF).

• paths – The paths to the results of the search, used to load the samples and search internal attributes if they are required and not available in memory.

• samples – The samples of the non-linear search, for example the MCMC chains.

• search_internal – The non-linear search used to perform the model fit in its internal format.

• analysis – The Analysis object that was used to perform the model-fit from which this result is inferred.

dict() → dict

Human-readable dictionary representation of the results

property projected_model: AbstractPriorModel

Create a new model with the same structure as the previous model, replacing each prior with a new prior created by calculating sufficient statistics from samples and corresponding weights for that prior.

property samples: Samples | None

Returns the samples of the non-linear search, for example the MCMC chains or nested sampling samples.

When a model-fit is run the first time, the samples are passed into the result via memory and therefore always available.

However, if a model-fit is resumed the samples are not available in memory and they only way to load them is via the samples.csv file output on the hard-disk. This property handles the loading of the samples from the samples.csv file if they are not available in memory.

Return type:

The samples of the non-linear search.

property search_internal

Returns the non-linear search used to perform the model fit in its internal sampler format.

When a model-fit is run the first time, the search internal is passed into the result via memory and therefore always available.

However, if a model-fit is resumed the search internal is not available in memory and they only way to load it is via the search_internal.dill file output on the hard-disk. This property handles the loading of the search internal from the search_internal.dill file if it is not available in memory.

Return type:

The non-linear search used to perform the model fit in its internal sampler format.

fit_for_visualization(instance)

Build the fit used by the visualizer.

Dispatch over self.fit_from with an opt-in jax.jit fast path:

• use_jax_for_visualization=False (default) — plain self.fit_from(instance). Untouched by JAX.

• use_jax_for_visualization=True — lazily construct jax.jit(self.fit_from) on the first call and cache it on the instance as _jitted_fit_from, then call that for every subsequent visualization. The first call pays the compile cost; subsequent calls reuse the cached compiled function.

Caching is per-Analysis instance so each analysis gets its own compiled function keyed off that instance’s closed-over state (self.dataset, self.settings, etc. — these ride as pytree aux data via register_instance_pytree(FitImaging, no_flatten=...) in PyAutoLens).

fit_from is defined by Analysis subclasses (e.g. AnalysisImaging), not the base class — this method is only callable on subclasses that provide it. Downstream visualizers should prefer this over calling fit_from directly so the JIT seam stays in one place.

For the JIT path to succeed, the Fit* return type (and every nested autoarray / galaxy / lens type it carries) must be pytree- registered. That wiring lives in each analysis subclass (see AnalysisImaging._register_fit_imaging_pytrees in PyAutoLens). Variants that have not yet been pytree-audited must leave use_jax_for_visualization at its default of False.

compute_latent_samples(samples: Samples, batch_size: int | None = None) → Samples | None

Compute latent variables from a model instance.

A latent variable is not itself a free parameter of the model but can be derived from it. Latent variables may provide physically meaningful quantities that help interpret a model fit, and their values (with errors) are stored in latent.csv in parallel with samples.csv.

This implementation is designed to be compatible with both NumPy and JAX:

• It is written to be side-effect free, so it can be JIT-compiled with jax.jit.

• It can be vectorized over many parameter sets at once using jax.vmap, enabling efficient batched evaluation of latent variables for multiple samples.

• Returned values should be simple JAX/NumPy scalars or arrays (no Python objects), so they can be stacked into arrays of shape (n_samples, n_latents) for batching.

• Any NaNs introduced (e.g. from invalid model states) can be masked or replaced downstream.

Parameters:

• parameters (array-like) – The parameter vector of the model sample. This will typically come from the non-linear search. Inside this method it is mapped back to a model instance via model.instance_from_vector.

• model (Model) – The model object defining how the parameter vector is mapped to an instance. Passed explicitly so that this function can be used inside JAX transforms (vmap, jit) with functools.partial.

Returns:

A tuple containing the latent variables in a fixed order: (intensity_total, magnitude, angle). Each entry may be NaN if the corresponding component of the model is not present.

Return type:

tuple of (float or jax.numpy scalar)

compute_latent_variables(parameters, model) → Dict[str, float]

Override to compute latent variables from the instance.

Latent variables are expressed as a dictionary: {“name”: value}

More complex models can be expressed by separating variables names by ‘.’ {“name.attribute”: value}

Parameters:

instance – An instance of the model.

Return type:

The computed latent variables.

with_model(model)

Associate an explicit model with this analysis. Instances of the model will be used to compute log likelihood in place of the model passed from the search.

Parameters:

model – A model to associate with this analysis

Return type:

An analysis for that model

modify_before_fit(paths: AbstractPaths, model: AbstractPriorModel)

Overwrite this method to modify the attributes of the Analysis class before the non-linear search begins.

An example use-case is using properties of the model to alter the Analysis class in ways that can speed up the fitting performed in the log_likelihood_function.

modify_after_fit(paths: AbstractPaths, model: AbstractPriorModel, result: Result)

Overwrite this method to modify the attributes of the Analysis class before the non-linear search begins.

An example use-case is using properties of the model to alter the Analysis class in ways that can speed up the fitting performed in the log_likelihood_function.

make_result(samples_summary: SamplesSummary, paths: AbstractPaths, samples: SamplesPDF | None = None, search_internal: object | None = None, analysis: object | None = None) → Result

Returns the Result of the non-linear search after it is completed.

The result type is defined as a class variable in the Analysis class. It can be manually overwritten by a user to return a user-defined result object, which can be extended with additional methods and attributes specific to the model-fit.

The standard Result object may include:

• The samples summary, which contains the maximum log likelihood instance and median PDF model.

• The paths of the search, which are used for loading the samples and search internal below when a search

is resumed.

• The samples of the non-linear search (e.g. MCMC chains) also stored in samples.csv.

• The non-linear search used for the fit in its internal representation, which is used for resuming a search

and making bespoke visualization using the search’s internal results.

• The analysis used to fit the model (default disabled to save memory, but option may be useful for certain

projects).

Parameters:

• samples_summary – The summary of the samples of the non-linear search, which include the maximum log likelihood instance and median PDF model.

• paths – An object describing the paths for saving data (e.g. hard-disk directories or entries in sqlite database).

• samples – The samples of the non-linear search, for example the chains of an MCMC run.

• search_internal – The internal representation of the non-linear search used to perform the model-fit.

• analysis – The analysis used to fit the model.

Returns:

The result of the non-linear search, which is defined as a class variable in the Analysis class.

Return type:

Result

property supports_background_update: bool

Whether this analysis supports background quick updates.

property supports_jax_visualization: bool

Whether the visualizer can work directly with JAX arrays.

Derived from the use_jax_for_visualization flag passed at construction time. Subclasses may override to force a specific answer (e.g. an Analysis that has been audited to support JAX visualization unconditionally).

print_vram_use(model, batch_size: int) → str

Print JAX VRAM use for a given batch size.

Parameters:

batch_size – The batch size to profile, which is the number of model evaluations JAX will perform simultaneously.