autolens.analysis.model_util.mge_model_from

mge_model_from(mask_radius, total_gaussians=30, gaussian_per_basis=1, centre_prior_is_uniform=True, centre=(0.0, 0.0), centre_fixed=None, centre_per_basis=False, centre_sigma=0.3, ell_comps_prior_is_uniform=False, ell_comps_uniform_width=0.2, ell_comps_sigma=0.3, use_spherical=False, sigma_min=0.0001, ell_comps_limit=1.0, order_bases=False)

Construct a Multi-Gaussian Expansion (MGE) for the lens or source galaxy light.

This model is designed as a “start here” configuration for lens modeling:

• The lens and source light are represented by a Basis object composed of many Gaussian light profiles with fixed logarithmically spaced widths (sigma).

• All Gaussians within each basis share common centres and ellipticity components, reducing degeneracy while retaining flexibility.

• Users can combine with a lens mass model of their choice.

When gaussian_per_basis > 1, each basis receives independent ellipticity components (ell_comps), allowing the model to represent twisting or varying isophotes across different radial scales. Centres are shared across bases by default (the common case: one luminosity centre, complex isophotal shape). Set centre_per_basis=True to give each basis its own centre priors.

Expected free-parameter counts (elliptical, use_spherical=False):

• gaussian_per_basis=1 : 2 centre + 2 ell_comps = 4

• gaussian_per_basis=K (shared centre) : 2 + 2K

• gaussian_per_basis=K, centre_per_basis=True : 2K + 2K = 4K

Spherical (use_spherical=True): no ell_comps, only centres.

• Shared centre: 2. Per-basis centre: 2K.

Parameters:

• mask_radius (float) – The outer radius (in arcseconds) of the circular mask applied to the data. This determines the maximum Gaussian width (sigma) used in the MGE.

• total_gaussians (int) – Total number of Gaussian light profiles used in each basis.

• gaussian_per_basis (int) – Number of separate Gaussian bases. Each basis has total_gaussians components sharing the same centre and ellipticity. Multiple bases allow independent ellipticity (and optionally centre) per radial scale group.

• centre_prior_is_uniform (bool) – If True (default), centre priors are UniformPrior(±0.1) around centre. If False, GaussianPrior with centre_sigma.

• centre (Tuple[float, float]) – (y, x) centre in arcseconds used as the mean/midpoint for centre priors.

• centre_fixed (Optional[Tuple[float, float]]) – If not None, fix all Gaussian centres to this (y, x) value instead of making them free parameters. Overrides centre_per_basis.

• centre_per_basis (bool) – If True, each basis gets independently drawn centre priors. If False (default), all bases share the same centre. Ignored when centre_fixed is set.

• centre_sigma (float) – Sigma for GaussianPrior centre priors (used when centre_prior_is_uniform=False).

• ell_comps_prior_is_uniform (bool) – If True, ell_comps priors are UniformPrior. If False (default), TruncatedGaussianPrior.

• ell_comps_uniform_width (float) – Half-width for uniform ell_comps priors.

• ell_comps_sigma (float) – Sigma for truncated-Gaussian ell_comps priors.

• use_spherical (bool) – If True, use GaussianSph (no ell_comps). If False (default), use Gaussian with ellipticity.

• sigma_min (float) – The smallest Gaussian width (sigma) in arcseconds, which sets the lower end of the log-spaced sigma values. Defaults to 1e-4. Increase it (e.g. to a tenth of the pixel scale) to stop the basis wasting components on scales the data cannot resolve.

• ell_comps_limit (float) –

  Half-width of the box the truncated-Gaussian ell_comps priors are truncated to, giving lower_limit=-ell_comps_limit and upper_limit=+ell_comps_limit. Must satisfy 0.0 < ell_comps_limit <= 1.0; the default 1.0 is the full physical range. Uniform ell_comps priors are unaffected – their width is set by ell_comps_uniform_width.

  Callers tighten this box when the science case bounds the isophotal ellipticity: the Euclid strong-lens pipeline uses 0.5 for the lens light and 0.7 for the source. Setting the box here rather than overwriting the priors on the returned model keeps the prior objects the ones this function built, which matters because order_bases attaches an assertion that references them.

• order_bases (bool) –

  If True, require the bases’ shared ell_comps_1 values to be strictly decreasing, basis_0 > basis_1 > ... > basis_{K-1}, via K - 1 assertions added to the returned model. Defaults to False (off until validated on production runs). A no-op when gaussian_per_basis == 1; a ValueError when use_spherical=True, which has no ell_comps to order.

  The symmetry. With gaussian_per_basis=K > 1 every basis holds the same total_gaussians linear Gaussians on the same fixed log10_sigma_list, and differs from its siblings only in the ellipticity pair it carries. The bases are therefore exchangeable: permuting which basis holds which ell_comps leaves the likelihood exactly unchanged, so the posterior has K! identical modes and an unseeded search lands in whichever one it reaches first. Repeat fits of the same data then report the same physical solution under swapped labels, which breaks any downstream comparison that reads basis_0 as a fixed component. Ordering the bases picks one labelling and deletes the other K! - 1 copies; it removes no physical solution.

  Why ``ell_comps_1`` and not the magnitude. The key must separate the modes the search actually finds. At the maximum-likelihood point either key admits exactly one permutation, so the choice is not about which key can order a single point – it is about the posterior spread. The two modes are separated in the key by |key(e_A) - key(e_B)|, and when that separation is smaller than the marginal posterior width in the key the constraint surface passes through both modes: the retained region mixes the two labellings and the labels are still undetermined. On the Euclid phase-4 tiles the two bases commonly sit against opposite edges of the ell_comps box, e.g. (0.007, -0.500) and (-0.023, 0.497). For that pair the magnitude separation is 0.0025 while the ell_comps_1 separation is 1.0, so the cos 2phi component separates the modes by far more than any plausible marginal width and the magnitude does not.

  Blind band. No continuous key is exact for every configuration – another tile has the two bases only 0.01 apart in ell_comps_1, a separation small compared with a typical marginal posterior width, so there too the constraint surface passes through both modes and ordering by ell_comps_1 does not resolve that tile. The diagnostic is a small |delta ell_comps_1| relative to the posterior width: read such a result as undetermined labelling rather than as an ordered answer.

  Consequences of an assertion being part of the model. It enters the PyAutoFit identifier, so turning order_bases on gives an otherwise identical fit a new unique_id and a fresh output directory – with PyAutoFit at or after the identifier fix that ships alongside this option (PyAutoFit#1581 follow-up); on older PyAutoFit the ordered and unordered models share an identifier and an ordered fit would load a completed unordered result from the same directory. It also makes the model an invalid target for take_attributes: PyAutoFit’s assert_no_assertions refuses to copy attributes into a model that already carries assertions, so build the ordered model after any such prior-passing step. Prior passing in the other direction drops the ordering altogether: Result.model is built by gaussian_prior_model_for_arguments, which clears _assertions (PyAutoFit/autofit/mapper/prior_model/prior_model.py, line 601), so a model built from a result is unordered again – recompose the Basis with order_bases=True when chaining fits rather than reusing the result’s model. Enforcement is backend-specific but has the same outcome – NumPy raises af.exc.FitException from check_assertions and the search resamples; JAX cannot raise inside a trace and instead evaluates the assertions as a traced boolean and maps a violating model to the resample figure of merit (PyAutoFit #1583).

Returns:

An autofit.Model wrapping a Basis of linear Gaussians.

Return type:

af.Model