debrispy.eccentricity

Classes

`EccentricityDistribution`(a_min, a_max, ...)	Defines an eccentricity distribution ψ_e(e,a).
`EccentricityProfile`()	Abstract base class for eccentricity profiles.
`PowerLawEccentricity`(a_min, a_max, zeta, lam)	Eccentricity distribution psi(e,a) = (2zeta + 1) lambda(a)^(-(2zeta + 1)) e * (lambda(a)^2 - e^2)^(zeta - 1/2) defined for 0 ≤ e < lambda(a), with zeta > 0.
`RayleighEccentricity`(a_min, a_max[, sigma0, ...])	Eccentricity distribution assuming a properly normalized Rayleigh distribution.
`TopHatEccentricity`(a_min, a_max, lam[, ...])	Eccentricity distribution \(\psi(e,a) = (1 / \lambda(a)) * e / \sqrt(\lambda(a)^2 - e^2)\), which yields a step-function kernel \(\phi(kappa,a) = (\pi / 2\lambda(a)) · 1_{kappa <= \lambda(a)}\).
`TriangularEccentricity`(a_min, a_max, lam[, ...])	Eccentricity distribution: \(\psi(e,a) = (2e / \lambda(a)^2) * \ln[ (\lambda(a) + \sqrt(\lambda(a)^2 - e^2)) / e ]\), valid for \(0 \leq e < \lambda(a)\)
`TruncGaussEccentricity`(a_min, a_max, sigma, lam)	Truncated Gaussian eccentricity distribution with a normalisation term.
`UniqueEccentricity`(a_min, a_max[, ...])	Fixed eccentricity profile where eccentricity is a unique function of semi-major axis: e = e(a).

class debrispy.eccentricity.EccentricityDistribution(a_min: float, a_max: float, distribution_func: Callable[[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]], ndarray[tuple[int, ...], dtype[float64]]], num_e_points: int = 1000, num_a_points: int = 1000, interpolation_method: str | None = None, auto_normalise: bool = False, grid_type: str | None = None, grid_spread: float | None = 1.0)[source]

Bases: EccentricityProfile

Defines an eccentricity distribution ψ_e(e,a). Gridding and interpolation is required if auto_normalise is True, otherwise the distribution is determined directly via the distribution_func.

Parameters:

a_min (float) – Minimum semi-major axis.
a_max (float) – Maximum semi-major axis.
distribution_func (callable) – Function ψ_e(e,a) to sample; must accept array inputs for both e and a.
num_e_points (int, optional) – Number of points in e (default 1000).
num_a_points (int, optional) – Number of points in a (default 1000).
interpolation_method (str, optional) – ‘nearest’, ‘linear’ or ‘cubic’.
auto_normalise (bool, optional) – If True, normalise ψ_e along e for each a, this is done via gridding and interpolation.
grid_type (str, optional) – ‘uniform’, ‘warped’ or ‘adaptive’. (If auto_normalise is True, this must be provided.)
grid_spread (float, optional) – This is a parameter used in warped and adaptive gridding. The larger the grid_spread, the less concentrated the grid is around sharp features.

distribution(e: float | ndarray[tuple[int, ...], dtype[float64]], a: float | ndarray[tuple[int, ...], dtype[float64]]) → float | ndarray[tuple[int, ...], dtype[float64]][source]

Evaluate the distribution at the provided points.

If auto_normalise is True, the distribution is evaluated using the interpolator. If auto_normalise is False, the distribution is evaluated using analytic distribution function.

Parameters:

e (float or array-like) – Eccentricity values.
a (float or array-like) – Semi-major axis values.

Returns:

psi_e – Distribution values.

Return type:

float or array-like

eccentricity(a)[source]: Return the eccentricity e(a) at given semi-major axis a (for unique eccentricity profiles). Should be overridden by subclasses if applicable.

get_sampled_distribution() → Tuple[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]][source]

Get the sampled distribution (e_grid, a_grid, psi_grid).

If auto_normalise is True, the sampled distribution is the same as the grid data. If auto_normalise is False, the sampled distribution is the distribution function evaluated on the grid.

Returns:

e_grid (npt.NDArray[np.float64]) – Eccentricity grid.
a_grid (npt.NDArray[np.float64]) – Semi-major axis grid.
psi_grid (npt.NDArray[np.float64]) – Distribution values.

plot(save: bool = False, filename: str | None = None, log: bool = False, vmin: float | None = None, vmax: float | None = None, points: bool = False, point_size: float = 10, cmap: str = 'viridis') → None[source]

Plot the eccentricity distribution.

Parameters:

save (bool) – If True, save figure to filename.
filename (str) – Path to save the figure.
show_grid (bool) – Overlay the computational grid (only if auto_normalise=True).
log (bool) – Use logarithmic color scale.
vmin (float) – Color scale limits.
vmax (float) – Color scale limits.
points (bool) – Plot the distribution as points instead of a surface.
point_size (float) – Size of the points if points=True.
cmap (str) – Colormap to use.

plot_slice(*, fix_a: float | None = None, fix_e: float | None = None, num_points: int = 500, save: bool = False, filename: str | None = None, figsize: Tuple[int, int] = (8, 6), show: bool = True, ax: Axes | None = None, **plot_kwargs) → None[source]

Plot a 1D slice of the 2D eccentricity distribution psi(e, a).

Parameters:

fix_a (float, optional) – If provided, plots psi(e) at fixed semi-major axis a.
fix_e (float, optional) – If provided, plots psi(a) at fixed eccentricity e.
num_points (int, optional) – Number of points for plotting. Defaults to 500.
save (bool, optional) – If True, saves the figure instead of displaying. Defaults to False.
filename (str, optional) – Filename to save the figure. Required if save is True.
figsize (tuple, optional) – Figure size in inches. Defaults to (8, 6).
show (bool, optional) – Whether to show the plot. Defaults to True.
ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, a new figure is created.
**plot_kwargs (dict) – Additional keyword arguments for plt.plot.

Raises:

ValueError – If neither or both of fix_a and fix_e are provided.

class debrispy.eccentricity.EccentricityProfile[source]

Bases: object

Abstract base class for eccentricity profiles.

distribution(e, a)[source]: Return the eccentricity distribution ψ_e(e,a) (for distribution-based eccentricity profiles). Should be overridden by subclasses if applicable.

eccentricity(a)[source]: Return the eccentricity e(a) at given semi-major axis a (for unique eccentricity profiles). Should be overridden by subclasses if applicable.

plot(*args, **kwargs)[source]: Plot the eccentricity profile.

class debrispy.eccentricity.PowerLawEccentricity(a_min: float, a_max: float, zeta: float, lam: float | Callable[[float], float], num_e_points: int = 1000, num_a_points: int = 1000)[source]

Bases: EccentricityDistribution

Eccentricity distribution psi(e,a) = (2*zeta + 1) * lambda(a)^(-(2*zeta + 1)) * e * (lambda(a)^2 - e^2)^(zeta - 1/2) defined for 0 ≤ e < lambda(a), with zeta > 0.

Parameters:

a_min (float) – Minimum semi-major axis.
a_max (float) – Maximum semi-major axis.
zeta (float) – Power-law shape parameter (must satisfy ζ > 0).
lam (callable or float) – Function lambda(a). User can provide a callable or a constant lambda.
num_e_points (int, optional) – Number of eccentricity grid points.
num_a_points (int, optional) – Number of semi-major axis grid points.

class debrispy.eccentricity.RayleighEccentricity(a_min: float, a_max: float, sigma0: float | None = None, power: float | None = None, sigma_func: Callable[[float], float] | None = None, num_e_points: int = 1000, num_a_points: int = 1000)[source]

Bases: EccentricityDistribution

Eccentricity distribution assuming a properly normalized Rayleigh distribution.

Parameters:

a_min (float) – Minimum semi-major axis.
a_max (float) – Maximum semi-major axis.
sigma0 (float, optional) – Amplitude of the power-law scale function sigma(a). Required if sigma_func is not provided.
power (float, optional) – Power-law slope of sigma(a). Required if sigma_func is not provided.
sigma_func (callable, optional) – Custom function sigma(a). If provided, sigma0 and power must be omitted.
num_e_points (int) – Number of eccentricity grid points.
num_a_points (int) – Number of semi-major axis grid points.

class debrispy.eccentricity.TopHatEccentricity(a_min: float, a_max: float, lam: float | Callable[[float], float], num_e_points: int = 1000, num_a_points: int = 1000)[source]

Bases: EccentricityDistribution

Eccentricity distribution \(\psi(e,a) = (1 / \lambda(a)) * e / \sqrt(\lambda(a)^2 - e^2)\), which yields a step-function kernel \(\phi(kappa,a) = (\pi / 2\lambda(a)) · 1_{kappa <= \lambda(a)}\).

Parameters:

a_min (float) – Minimum semi-major axis.
a_max (float) – Maximum semi-major axis.
lam (callable or float) – The user can either provide a callable lambda(a) or a constant lambda0.
num_e_points (int, optional) – Number of eccentricity grid points.
num_a_points (int, optional) – Number of semi-major axis grid points.

class debrispy.eccentricity.TriangularEccentricity(a_min: float, a_max: float, lam: float | Callable[[float], float], num_e_points: int = 1000, num_a_points: int = 1000)[source]

Bases: EccentricityDistribution

Eccentricity distribution: \(\psi(e,a) = (2e / \lambda(a)^2) * \ln[ (\lambda(a) + \sqrt(\lambda(a)^2 - e^2)) / e ]\), valid for \(0 \leq e < \lambda(a)\)

Parameters:

a_min (float) – Minimum semi-major axis.
a_max (float) – Maximum semi-major axis.
lam (callable or float) – The user can either provide a callable lambda(a) or a constant lambda0.
num_e_points (int, optional) – Number of eccentricity grid points.
num_a_points (int, optional) – Number of semi-major axis grid points.

class debrispy.eccentricity.TruncGaussEccentricity(a_min: float, a_max: float, sigma: float | Callable[[float], float], lam: float | Callable[[float], float], num_e_points: int = 1000, num_a_points: int = 1000)[source]

Bases: EccentricityDistribution

Truncated Gaussian eccentricity distribution with a normalisation term.

psi(e, a) = sqrt(2/pi) * C(a) * [: exp(-e² / (2sigma_k(a)²)) / sigma_k(a) * erf( sqrt((lambda(a)² - e²) / (2sigma_k(a)²)) ) + sqrt(2/pi) * exp(-lambda(a)² / (2sigma_k(a)²)) / sqrt(lambda(a)² - e²)

]

Parameters:

a_min (float) – Minimum semi-major axis.
a_max (float) – Maximum semi-major axis.
sigma (float or callable) – Constant sigma or a function sigma(a). Must be > 0.
lam (float or callable) – Constant lambda or a function lambda(a). Must be 0 < lambda ≤ 1.
num_e_points (int) – Number of eccentricity grid points.
num_a_points (int) – Number of semi-major axis grid points.

class debrispy.eccentricity.UniqueEccentricity(a_min: float, a_max: float, eccentricity_func: Callable[[float | ndarray[tuple[int, ...], dtype[float64]]], ndarray[tuple[int, ...], dtype[float64]]] | None = None, e0: float = 1.0, power: float | None = None)[source]

Bases: EccentricityProfile

Fixed eccentricity profile where eccentricity is a unique function of semi-major axis: e = e(a).

By default implements a power-law profile e(a) = e0 * (a_min/a)^{power}, but accepts custom user-defined functions.

Parameters:

a_min (float) – Minimum semi-major axis.
a_max (float) – Maximum semi-major axis.
eccentricity_func (callable, optional) – Custom function e(a). If None, uses a default power-law form.
e0 (float, optional) – Normalization constant. Default is 1.0.
power (float, optional) – Power-law exponent for built-in power-law e(a) (required if eccentricity_func is None).

Raises:

ValueError – If the eccentricity function produces values outside the range [0, 1) across the specified semi-major axis range.

derivative(a: float | ndarray[tuple[int, ...], dtype[float64]]) → float | ndarray[tuple[int, ...], dtype[float64]][source]

Calculate the derivative de/da of the eccentricity profile using analytical or finite differences.

Parameters:: a (float or array-like) – Semi-major axis value(s).
Returns:: Derivative value(s) at the specified semi-major axis/axes.
Return type:: float or ndarray

distribution(e: float | ndarray[tuple[int, ...], dtype[float64]], a: float | ndarray[tuple[int, ...], dtype[float64]]) → None[source]

Distribution function ψ_e(e,a) is not defined for deterministic profiles.

Raises:: NotImplementedError – Always raised since fixed eccentricity profiles do not have a distribution.

eccentricity(a: float | ndarray[tuple[int, ...], dtype[float64]]) → float | ndarray[tuple[int, ...], dtype[float64]][source]

Return eccentricity value(s) at given semi-major axis/axes.

Parameters:: a (float or array-like) – Semi-major axis value(s).
Returns:: Eccentricity value(s) corresponding to the input semi-major axis/axes.
Return type:: ndarray

plot(a_vals: ndarray[tuple[int, ...], dtype[float64]] | None = None, num_points: int = 500, save: bool = False, filename: str | None = None, figsize: Tuple[int, int] = (8, 6), ax: Axes | None = None, show: bool = True, **plot_kwargs)[source]

Plot the eccentricity profile e(a) with flexible matplotlib customization.

Parameters:

(array-like (a_vals) – If None, generate new ones. Defaults to None.
optional) (Whether to display the plot. Defaults to True.) – If None, generate new ones. Defaults to None.
(int (num_points) – Defaults to 500.
optional) – Defaults to 500.
(bool (show)
optional)
(str (filename) – will be generated. Defaults to None.
optional) – will be generated. Defaults to None.
(tuple (figsize) – Defaults to (8, 6).
optional) – Defaults to (8, 6).
(matplotlib.axes.Axes (ax) – a new figure and axes will be created. Defaults to None.
optional) – a new figure and axes will be created. Defaults to None.
(bool
optional)
**plot_kwargs (Additional keyword arguments passed to plt.plot() and ax.set().) –
Examples include:
- color: Color of the line
- linestyle: Style of the line (‘-’, ‘–’, ‘-.’, ‘:’)
- linewidth or lw: Width of the line
- marker: Point marker style (‘o’, ‘s’, ‘^’, etc.)
- alpha: Transparency of the line
- label: Label for the legend
- log (bool): Whether to use a logarithmic scale for the y-axis.
- xlim (tuple): Limits for the x-axis.
- ylim (tuple): Limits for the y-axis.
- xlabel (str): Custom x-axis label.
- ylabel (str): Custom y-axis label.
- title (str): Plot title.
- grid (bool): Whether to show the grid.

Raises:

ValueError – If save=True but no filename is provided.: