socca.models.ellipsoid¶

Ellipsoid model component.

class socca.models.ellipsoid.Ellipsoid(radial=None, **kwargs)[source]¶

Bases: Component

3D triaxial-ellipsoid model evaluated via line-of-sight integration.

Projects an ellipsoidal Sersic-like density onto the sky by integrating along the line of sight, in the same spirit as Disk but using a single radial profile for shape rather than separate radial/vertical profiles. A common use case is modeling a galactic bar embedded within a host Disk, with its position, position angle, and inclination tied to the disk’s via boundto() – see the Examples below and socca.priors.boundto(). xc, yc, theta, e, eratio, inc, rot, losdepth, and losbins live directly on Ellipsoid; radial only supplies the brightness-shape parameters (re, Ie, ns for Sersic).

The ellipsoid has one major semi-axis (along x) and two minor semi-axes (along y and z), which need not be equal: e sets the ellipticity in the (x, y) plane – the plane that corresponds to the projected ellipse when the ellipsoid is seen face-on (inc = 0) – and eratio sets the ratio of the z axis’s ellipticity to e, so the two minor axes can differ.

Parameters:

radial (Profile, optional) – Profile defining the ellipsoid’s brightness-shape parameters (re, Ie, ns for Sersic). Default is Sersic(). Any xc/yc/theta/e already set on it are inherited by Ellipsoid unless also passed as an Ellipsoid keyword argument, in which case Ellipsoid’s value wins and a warning is raised.
xc (float, optional) – Right ascension and declination of the ellipsoid centroid (deg).
yc (float, optional) – Right ascension and declination of the ellipsoid centroid (deg).
theta (float, optional) – Position angle, east from north (rad).
e (float, optional) – Ellipticity (1 - axis ratio) between the major (x) axis and the first minor (y) axis – i.e. the ellipticity of the face-on projected ellipse.
eratio (float, optional) – Ratio in [0, 1] of the second minor (z) axis’s ellipticity to e: z-axis ellipticity = eratio * e. Default is 1, which makes both minor axes equal (a prolate/oblate spheroid rather than a fully triaxial ellipsoid).
inc (float, optional) – Inclination angle (0 = face-on). Typically tied to a host Disk’s inclination via boundto().
rot (float, optional) – Rotation applied after inclining, within the ellipsoid’s own tilted frame. Only equivalent to a position-angle offset (i.e. theta + rot) when inc = 0.
losdepth (float, optional) – Half line-of-sight extent for integration.
losbins (int, optional) – Number of points for line-of-sight integration.
**kwargs (dict) – Additional keyword arguments passed to Component.

Variables:

radial (Profile) – Radial brightness-shape profile component.
profile (callable) – JIT-compiled 3D density profile evaluated on the (x, y, z) grid.

Examples

>>> from socca.models import Ellipsoid, Sersic
>>> ellipsoid = Ellipsoid(radial=Sersic(re=2e-4, Ie=10.0, ns=0.25))
>>> ellipsoid.xc, ellipsoid.yc, ellipsoid.theta, ellipsoid.e = (
...     180.5, 45.2, 0.5, 0.7
... )
>>> ellipsoid.inc, ellipsoid.rot = 1.0, 0.2

Tying a galactic bar’s geometry to that of a host Disk:

>>> from socca.models import Disk
>>> from socca.priors import boundto
>>> disk = Disk()
>>> bar = Ellipsoid()
>>> bar.xc = boundto(disk, "xc")
>>> bar.yc = boundto(disk, "yc")
>>> bar.theta = boundto(disk, "theta")
>>> bar.inc = boundto(disk, "inc")

property e¶

property eratio¶

property theta¶

property rot¶

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

Generate ellipsoid image via 3D line-of-sight integration.

Computes the projected surface brightness by integrating the 3D ellipsoidal density along the line of sight, accounting for inclination and intrinsic rotation.

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:

Projected ellipsoid image on the image grid.

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.

Notes

Integration accuracy is controlled by losdepth (extent) and losbins (number of points); increase both for highly inclined ellipsoids.

Examples

>>> from socca.models import Ellipsoid, Sersic
>>> from socca.data import Image
>>> ellipsoid = Ellipsoid(radial=Sersic(re=2e-4, Ie=10.0, ns=0.25))
>>> ellipsoid.xc, ellipsoid.yc, ellipsoid.theta, ellipsoid.e = (
...     180.5, 45.2, 0.5, 0.7
... )
>>> ellipsoid.inc, ellipsoid.rot = 1.0, 0.2
>>> img = Image('observation.fits')
>>> ellipsoid_map = ellipsoid.getmap(img, convolve=True)

static getgrid(grid, xc, yc, losdepth, losbins=200, theta=0.0, inc=0.0, rot=0.0)[source]¶

Compute 3D ellipsoid coordinates with position angle, inclination, and rotation.

Generates 3D coordinate grids (x, y, z) for ellipsoid model evaluation, accounting for the position angle, inclination, and intrinsic rotation transformations needed for line-of-sight integration through an inclined, rotated ellipsoid.

Parameters:

grid (Grid) – Grid object with .x and .y celestial coordinate arrays (deg).
xc (float) – Right ascension of ellipsoid center (deg).
yc (float) – Declination of ellipsoid center (deg).
losdepth (float) – Half-extent of line-of-sight integration (deg).
losbins (int, optional) – Number of integration points along line of sight. Default is 200.
theta (float, optional) – Position angle, east from north (rad). Default is 0.
inc (float, optional) – Inclination angle (0 = face-on, pi/2 = edge-on) (rad). Default is 0.
rot (float, optional) – Rotation applied after inclining, within the already-inclined frame (rad). Default is 0. Only equivalent to a position-angle offset (i.e. theta + rot) when inc = 0 – see Notes.

Returns:

xt, yt, zt – 4D arrays of ellipsoid-frame coordinates (deg). Shape: (ssize, losbins, ysize, xsize).

Return type:

ndarray

Notes

The transformation sequence: 1. Center coordinates on (xc, yc) and apply spherical geometry correction (cos(dec)) 2. Rotate by position angle theta, with a 90-degree offset to match Disk’s convention 3. Create the line-of-sight grid from -losdepth to +losdepth and broadcast to 4D 4. Incline around the y-axis, mixing the position-angle-rotated x with the line-of-sight coordinate 5. Rotate by rot within that already-inclined (x, y) frame

Because step 4 mixes the line-of-sight coordinate into x before step 5 runs, rot is not simply an additive offset to theta except in the face-on case (inc = 0): for inc != 0, rotating by rot after inclining is a genuinely different transform from inclining after rotating by theta + rot.

parameters()[source]¶

Print formatted table of ellipsoid parameters from the radial component.

Displays parameters from both the radial sub-component (prefixed as ‘radial.parameter’) and Ellipsoid’s own xc/yc/theta/e/eratio/inc/rot. Separates regular parameters from hyperparameters (integration settings).

Notes

Output format:

Model parameters¶

Hyperparameters¶

losdepth [deg] : value | Half line-of-sight extent losbins [] : value | Number of integration points

Examples

>>> from socca.models import Ellipsoid, Sersic
>>> ellipsoid = Ellipsoid(radial=Sersic(re=2e-4, Ie=10.0, ns=0.25))
>>> ellipsoid.xc, ellipsoid.yc, ellipsoid.theta, ellipsoid.e = (
...     180.5, 45.2, 0.5, 0.7
... )
>>> ellipsoid.parameters()
Model parameters
================
radial.re         [deg]    : 2.0000E-04 | Effective radius
...

parlist()[source]¶

Return list of parameter names from the radial component and Ellipsoid itself.

Returns:: Combined list of parameter names: radial’s shape parameters (prefixed ‘radial.’) plus Ellipsoid’s own xc, yc, theta, e, eratio, inc, rot, losdepth, losbins.
Return type:: list of str

Notes

This method is used internally by Model.addcomponent() when adding an Ellipsoid component to a composite model, ensuring all parameters are registered.

Examples

>>> from socca.models import Ellipsoid, Sersic
>>> ellipsoid = Ellipsoid(radial=Sersic(re=2e-4, Ie=10.0, ns=0.25))
>>> ellipsoid.parlist()
['radial.re', 'radial.Ie', 'radial.ns', 'xc', 'yc', 'theta', 'e',
 'eratio', 'inc', 'rot', 'losdepth', 'losbins']