socca.models.radial¶

Radial surface brightness profile models.

class socca.models.radial.Profile(**kwargs)[source]¶

Bases: Component

Base class for 2D surface brightness profiles.

This class extends Component to provide common coordinate transformation and projection parameters (position, orientation, ellipticity, boxiness) for all 2D surface brightness profiles.

Parameters:

**kwargs (dict) –

Keyword arguments for profile initialization including:

xcfloat, optional: Right ascension of profile centroid (deg).
ycfloat, optional: Declination of profile centroid (deg).
thetafloat, optional: Position angle measured east from north (rad).
efloat, optional: Ellipticity, defined as 1 - b/a where b/a is axis ratio (0 <= e < 1).
cboxfloat, optional: Boxiness parameter (0 = elliptical, >0 = boxy, <0 = disky).
positivebool, optional: Whether to enforce positivity constraint.

Variables:

yc (xc,) – Centroid coordinates in celestial degrees.
theta (float) – Position angle in radians.
e (float) – Ellipticity parameter.
cbox (float) – Boxiness/diskyness parameter.

Notes

All Profile subclasses must implement the abstract profile() method that defines the radial surface brightness distribution.

__init__(**kwargs)[source]¶

Initialize a profile with standard coordinate and shape parameters.

Parameters:: **kwargs (dict) – Keyword arguments including xc, yc, theta, e, cbox, positive. See class docstring for parameter descriptions.

property e¶

abstractmethod profile(r)[source]¶

Abstract method defining the radial profile function.

Subclasses must implement this method to define the surface brightness distribution as a function of radius and other profile-specific parameters.

Parameters:: r (ndarray) – Radial coordinate in degrees.
Returns:: Surface brightness values at each radius.
Return type:: ndarray

getmap(img, convolve=False)[source]¶

Generate an image map from the profile on the given grid.

Evaluates the profile on the image grid and optionally convolves with the PSF. All parameters must have fixed values.

Parameters:

img (Image) – Image object containing grid, PSF, and WCS information.
convolve (bool, optional) – If True, convolve the model with the PSF. Default is False.

Returns:

2D array of surface brightness values on the image grid. Shape matches img.data.shape.

Return type:

ndarray

Raises:

ValueError – If any parameter is a prior distribution or set to None.

Warns:

UserWarning – If convolve=True but no PSF is defined in img.

Notes

All profile parameters must be fixed values (not distributions).
The elliptical grid is computed using position, ellipticity, and PA.
Convolution is performed in Fourier space for efficiency.

Examples

>>> from socca.models import Beta
>>> from socca.data import Image
>>> beta = Beta(xc=180.5, yc=45.2, rc=0.01, Ic=100, beta=0.5)
>>> img = Image('observation.fits')
>>> model_map = beta.getmap(img, convolve=True)

static getgrid(grid, xc, yc, theta=0.0, e=0.0, cbox=0.0)[source]¶

Compute elliptical radius grid with rotation and projection.

This static JIT-compiled method transforms celestial coordinates to elliptical radius values accounting for position angle, ellipticity, and boxiness. Used internally by profile evaluation.

Parameters:

grid (Grid) – Grid object with .x and .y celestial coordinate arrays (deg).
xc (float) – Right ascension of centroid (deg).
yc (float) – Declination of centroid (deg).
theta (float, optional) – Position angle east from north (rad). Default is 0.
e (float, optional) – Ellipticity (1 - b/a). Default is 0 (circular).
cbox (float, optional) – Boxiness parameter. Default is 0 (elliptical).

Returns:

Elliptical radius grid in degrees. Same shape as grid.x and grid.y.

Return type:

ndarray

Notes

The transformation accounts for:

Spherical geometry (cos(dec) correction)
Position angle rotation
Ellipticity via axis ratio correction
Generalized elliptical isophotes with boxiness

The elliptical radius is computed as: r = [(abs(x’)^(2+c) + abs(y’/(1-e))^(2+c)]^(1/(2+c)) where c is the boxiness parameter.

This function is JIT-compiled for performance during model evaluation.

refactor()[source]¶

Return a refactored version of the profile with equivalent parameterization.

For most profiles, this returns a copy of the profile with the same parameters. Some profiles (e.g., PolyExpoRefact) override this to convert to an alternative parameterization.

Returns:: A new profile instance with refactored parameterization.
Return type:: Profile
Warns:: UserWarning – Warns that this profile has no alternative parameterization.

Examples

>>> from socca.models import Beta
>>> beta = Beta(xc=180.5, yc=45.2)
>>> beta_refactored = beta.refactor()

class socca.models.radial.CustomProfile(parameters, profile, **kwargs)[source]¶

Bases: Profile

User-defined custom surface brightness profile.

Allows users to define arbitrary profile functions with custom parameters, enabling modeling of non-standard surface brightness distributions.

Parameters:

parameters (list of dict) –
List of parameter specifications. Each dict should contain:
- ’name’: str, parameter name
- ’unit’: str, optional, physical unit (default: ‘not specified’)
- ’description’: str, optional, parameter description
profile (callable) – Function defining the profile. Should have signature profile(r, **params) where r is the elliptical radius and **params are the custom parameters.
**kwargs (dict) – Standard profile parameters (xc, yc, theta, e, cbox, positive).

Notes

The profile function is automatically JIT-compiled for performance.
All parameters in the parameters list are initialized to None and must be set before use.
The profile function should be compatible with JAX (use jax.numpy operations).

Examples

>>> from socca.models import CustomProfile
>>> import jax.numpy as jp
>>> # Define a custom Gaussian profile
>>> def gaussian_profile(r, amplitude, sigma):
...     return amplitude * jp.exp(-0.5 * (r / sigma)**2)
>>> params = [
...     {'name': 'amplitude', 'unit': 'image', 'description': 'Peak value'},
...     {'name': 'sigma', 'unit': 'deg', 'description': 'Gaussian width'}
... ]
>>> profile = CustomProfile(params, gaussian_profile, xc=180.5, yc=45.2)
>>> profile.amplitude = 100.0
>>> profile.sigma = 0.01

__init__(parameters, profile, **kwargs)[source]¶

Initialize a custom profile with user-defined parameters and function.

Parameters:

parameters (list of dict) – Parameter specifications with ‘name’, ‘unit’, and ‘description’.
profile (callable) – Profile function with signature profile(r, **params).
**kwargs (dict) – Standard profile parameters (xc, yc, theta, e, cbox).

class socca.models.radial.TopHat(**kwargs)[source]¶

Bases: Profile

Top-hat surface brightness profile.

The Top-hat profile describes a uniform surface brightness distribution within a cutoff radius: I(r) = 1 for |r| < rc, and I(r) = 0 otherwise. This profile is useful for modeling flat-topped emission regions.

static profile(r, rc, Ic)[source]¶

Top-hat surface brightness distribution.

Parameters:

r (ndarray) – Elliptical radius in degrees.
rc (float) – Cutoff radius in degrees.

Returns:

Surface brightness at radius r.

Return type:

ndarray

Notes

The Top-hat profile is defined as:

I(r) = 1 for |r| < rc, and I(r) = 0 otherwise

This profile produces a flat, uniform emission within the cutoff radius and zero emission outside.

class socca.models.radial.Sersic(**kwargs)[source]¶

Bases: Profile

Sersic profile for modeling elliptical galaxies and bulges.

The Sersic profile is a generalization of de Vaucouleurs’ law that describes the light distribution in elliptical galaxies and galactic bulges. The profile shape is controlled by the Sersic index (ns), with ns=1 corresponding to an exponential disk and ns=4 to a de Vaucouleurs profile.

property ns¶

static profile(r, Ie, re, ns)[source]¶

Sersic profile surface brightness distribution.

The Sersic profile is a generalization of de Vaucouleurs’ law and describes the light distribution in elliptical galaxies and bulges.

Parameters:

r (ndarray) – Elliptical radius in degrees.
Ie (float) – Surface brightness at the effective radius (same units as image).
re (float) – Effective (half-light) radius in degrees.
ns (float) –
Sersic index (concentration parameter). Typical values:
- ns = 0.5-1: disk-like profiles
- ns = 4: de Vaucouleurs profile (elliptical galaxies)
- ns > 4: highly concentrated profiles

Returns:

Surface brightness at radius r.

Return type:

ndarray

Notes

The Sersic profile is defined as: I(r) = Ie * exp(-bn * [(r/re)^(1/ns) - 1])

where bn is chosen such that re encloses half the total light. The parameter bn is approximated numerically and interpolated.

Common special cases:

ns = 1: Exponential profile
ns = 4: de Vaucouleurs profile (elliptical galaxies)

The valid range for ns is approximately 0.25 to 10.

References

Sersic, J. L. 1968, Atlas de Galaxias Australes Ciotti, L., & Bertin, G. 1999, A&A, 352, 447

Examples

>>> import jax.numpy as jp
>>> from socca.models import Sersic
>>> r = jp.linspace(0, 0.1, 100)
>>> # de Vaucouleurs profile for elliptical galaxy
>>> I = Sersic.profile(r, Ie=50.0, re=0.02, ns=4.0)

class socca.models.radial.Gaussian(**kwargs)[source]¶

Bases: Profile

Gaussian surface brightness profile.

The Gaussian profile describes a surface brightness distribution that follows a Gaussian function of radius: I(r) = Is * exp(-0.5 * (r/rs)^2). This profile is equivalent to a Sersic profile with index n=0.5.

__init__(**kwargs)[source]¶

Initialize a Gaussian profile component.

Parameters:

**kwargs (dict) –

Keyword arguments including:

rsfloat, optional: Scale radius (standard deviation) in degrees.
Isfloat, optional: Central surface brightness (same units as image).
xc, ycfloat, optional: Centroid coordinates (inherited from Profile).
thetafloat, optional: Position angle in radians (inherited from Profile).
efloat, optional: Projected axis ratio (inherited from Profile).
cboxfloat, optional: Projected boxiness (inherited from Profile).

static profile(r, Is, rs)[source]¶

Gaussian surface brightness distribution.

Parameters:

r (ndarray) – Elliptical radius in degrees.
Is (float) – Central surface brightness (same units as image).
rs (float) – Scale radius (standard deviation) in degrees.

Returns:

Surface brightness at radius r.

Return type:

ndarray

Notes

The Gaussian profile is defined as:

I(r) = Is * exp(-0.5 * (r / rs)^2)

This is equivalent to a Sersic profile with n=0.5. The scale radius rs corresponds to the standard deviation of the Gaussian, and the half-width at half-maximum (HWHM) is approximately 1.177 * rs.

class socca.models.radial.Beta(**kwargs)[source]¶

Bases: Profile

Beta profile for modeling galaxy clusters and elliptical galaxies.

The Beta profile describes a power-law density distribution commonly used for X-ray and radio observations of galaxy clusters. It has the form I(r) = Ic * (1 + (r/rc)^2)^(-beta).

static profile(r, Ic, rc, alpha, beta)[source]¶

Beta profile surface brightness distribution.

The Beta profile describes a power-law density distribution commonly used for modeling galaxy clusters and elliptical galaxies.

Parameters:

r (ndarray) – Elliptical radius in degrees.
Ic (float) – Central surface brightness (same units as image).
rc (float) – Core radius in degrees.
alpha (float) – Radial exponent parameter (default 2.0 for standard Beta profile).
beta (float) – Slope parameter (typically 0.4-1.0 for galaxy clusters).

Returns:

Surface brightness at radius r.

Return type:

ndarray

Notes

The generalized Beta profile is defined as: I(r) = Ic * [1 + (r/rc)^alpha]^(-beta)

With alpha=2, this reduces to the standard Beta profile commonly used in X-ray astronomy for modeling hot gas in galaxy clusters.

References

Cavaliere, A., & Fusco-Femiano, R. 1976, A&A, 49, 137

Examples

>>> import jax.numpy as jp
>>> from socca.models import Beta
>>> r = jp.linspace(0, 0.1, 100)
>>> I = Beta.profile(r, Ic=100.0, rc=0.01, alpha=2.0, beta=0.5)

class socca.models.radial.gNFW(**kwargs)[source]¶

Bases: Profile

Generalized Navarro-Frenk-White (gNFW) profile.

The gNFW profile is a flexible three-parameter model commonly used to describe the surface brightness distribution of galaxy clusters. It generalizes the NFW profile with adjustable inner (gamma), intermediate (alpha), and outer (beta) slopes.

property alpha¶

property beta¶

property gamma¶

class socca.models.radial.Power(**kwargs)[source]¶

Bases: Profile

Power law profile for surface brightness modeling.

The Power profile describes a simple power-law distribution of the form I(r) = Ic * (r/rc)^alpha.

static profile(r, Ic, rc, alpha)[source]¶

Power law surface brightness distribution.

Parameters:

r (ndarray) – Elliptical radius in degrees.
Ic (float) – Characteristic surface brightness (same units as image).
rc (float) – Scale radius in degrees.
alpha (float) – Power law slope parameter.

Returns:

Surface brightness at radius r.

Return type:

ndarray

Notes

The Power law profile is defined as: I(r) = Ic * (r/rc)^(-alpha)

For positive alpha values, the profile decreases with radius.

Examples

>>> import jax.numpy as jp
>>> from socca.models import Power
>>> r = jp.linspace(0.001, 0.1, 100)
>>> I = Power.profile(r, Ic=100.0, rc=0.01, alpha=2.0)

class socca.models.radial.Exponential(**kwargs)[source]¶

Bases: Profile

Exponential disk profile.

The exponential profile (Sersic index n=1) is the standard model for disk galaxies. It describes a surface brightness distribution that decays exponentially with radius: I(r) = Is * exp(-r/rs).

static profile(r, Is, rs)[source]¶

Exponential disk profile surface brightness distribution.

The exponential profile (Sersic index n=1) describes the light distribution in disk galaxies and spiral arms.

Parameters:

r (ndarray) – Elliptical radius in degrees.
Is (float) – Central surface brightness (same units as image).
rs (float) – Scale radius (scale length) in degrees.

Returns:

Surface brightness at radius r.

Return type:

ndarray

Notes

The exponential profile is defined as: I(r) = Is * exp(-r / rs)

This is a special case of the Sersic profile with n=1 and is the canonical profile for modeling disk galaxies. The scale radius rs contains about 63% of the total light within that radius.

The exponential profile has no finite effective radius; the half-light radius is approximately 1.678 * rs.

References

Freeman, K. C. 1970, ApJ, 160, 811 van der Kruit, P. C., & Searle, L. 1981, A&A, 95, 105

Examples

>>> import jax.numpy as jp
>>> from socca.models import Exponential
>>> r = jp.linspace(0, 0.1, 100)
>>> I = Exponential.profile(r, Is=100.0, rs=0.02)

class socca.models.radial.PolyExponential(**kwargs)[source]¶

Bases: Exponential

Exponential profile with polynomial modulation.

Extended exponential profile that includes polynomial terms to model deviations from a pure exponential disk. Based on the formalism from Mancera Pina et al., A&A, 689, A344 (2024).

static profile(r, Is, rs, c1, c2, c3, c4, rc)[source]¶

Polynomial-exponential profile surface brightness distribution.

An exponential profile modulated by a 4th-order polynomial, providing flexibility to model deviations from pure exponential profiles in disk galaxies.

Parameters:

r (ndarray) – Elliptical radius in degrees.
Is (float) – Central surface brightness (same units as image).
rs (float) – Exponential scale radius in degrees.
c1 (float) – Polynomial coefficients for 1st through 4th order terms.
c2 (float) – Polynomial coefficients for 1st through 4th order terms.
c3 (float) – Polynomial coefficients for 1st through 4th order terms.
c4 (float) – Polynomial coefficients for 1st through 4th order terms.
rc (float) – Reference radius for polynomial terms in degrees.

Returns:

Surface brightness at radius r.

Return type:

ndarray

Notes

The profile is defined as:

I(r) = Is * exp(-r/rs) * [1 + c1*(r/rc) + c2*(r/rc)^2

c3*(r/rc)^3 + c4*(r/rc)^4]

This profile allows modeling of:

Truncations or drops in outer regions
Central enhancements or deficits
Breaks in disk profiles
Type I, II, and III disk breaks

The polynomial modulation is normalized to the reference radius rc, which should typically be comparable to the scale radius rs.

References

Mancera Pina et al., A&A, 689, A344 (2024)

Examples

>>> import jax.numpy as jp
>>> from socca.models import PolyExponential
>>> r = jp.linspace(0, 0.1, 100)
>>> # Profile with slight central enhancement
>>> I = PolyExponential.profile(r, Is=100.0, rs=0.02, c1=0.1,
...                             c2=-0.05, c3=0.0, c4=0.0, rc=0.02)

class socca.models.radial.PolyExpoRefact(**kwargs)[source]¶

Bases: Exponential

Refactored polynomial exponential profile with intensity coefficients.

Alternative parameterization of the polynomial exponential profile using intensity coefficients instead of polynomial coefficients. Based on the formalism from Mancera Pina et al., A&A, 689, A344 (2024).

static profile(r, Is, rs, I1, I2, I3, I4, rc)[source]¶

Refactored polynomial-exponential profile using intensity coefficients.

Alternative parameterization of the polynomial-exponential profile using intensity coefficients rather than dimensionless polynomial coefficients.

Parameters:

r (ndarray) – Elliptical radius in degrees.
Is (float) – Central surface brightness (same units as image).
rs (float) – Exponential scale radius in degrees.
I1 (float) – Intensity coefficients for polynomial terms (same units as Is).
I2 (float) – Intensity coefficients for polynomial terms (same units as Is).
I3 (float) – Intensity coefficients for polynomial terms (same units as Is).
I4 (float) – Intensity coefficients for polynomial terms (same units as Is).
rc (float) – Reference radius for polynomial terms in degrees.

Returns:

Surface brightness at radius r.

Return type:

ndarray

Notes

The profile is defined as:

I(r) = exp(-r/rs) * [Is + I1*(r/rc) + I2*(r/rc)^2

I3*(r/rc)^3 + I4*(r/rc)^4]

This is mathematically equivalent to PolyExponential but uses intensity coefficients Ii instead of dimensionless coefficients ci. The relation is:

Ii = ci * Is

This parameterization may be more intuitive when the polynomial terms represent physical contributions with intensity units.

References

Mancera Pina et al., A&A, 689, A344 (2024)