Unitless quantities methods (deprecated)¶

class pNbody._unitless_quantities_deprecated_mixin._NbodyUnitlessQuantitiesDeprecatedMixin¶

Bases: object

Mixin providing methods to compute intrinsic physical properties from raw simulation data.

This class calculates quantities derived directly from the state vectors (positions, velocities, masses, etc.) stored in the simulation snapshots. These properties are ‘dimensionless’ or ‘unit-less,’ meaning they are expressed in the simulation’s internal coordinate system.

To obtain values in physical units (e.g., kpc, Msun, km/s), the outputs of these methods must be scaled by the appropriate transformation factors defined by the simulation’s normalization.

Primary computations include: * Density Profiles: Radial and projected number/mass densities. * Kinematic Profiles: Velocity dispersions and relative speed estimates. * Structural Profiles: Enclosed mass $M(<r)$ and specific angular momentum.

Deprecated since version 1.0: The profile-related routines in this mixin (dens, sdens, mr, etc.) are considered legacy. They rely on direct particle binning and histogramming. For higher performance, improved smoothing, and consistency with gravitational solvers, these should be replaced by the grid-based methods defined in libgrid.

Mr_Spherical(nr=25, rmin=0, rmax=50)¶

Compute the cumulative mass profile M(<r) using a 1D mapping technique.

This method calculates the integrated mass within spherical shells by mapping particle masses onto a 1D grid and performing a prefix sum. This is functionally similar to a cumulative histogram but uses the internal mapping module for potentially faster execution.

Parameters

nr (int, optional) – Number of radial bins. Default is 25.
rmin (float, optional) – The minimum radius for the mapping. Note that for a correct enclosed mass calculation, this should generally be 0. Default is 0.
rmax (float, optional) – The maximum radius for the mapping. Default is 50.

Returns

rs (ndarray) – A 1D array of the radial bin edges.
m_enclosed (ndarray) – A 1D array containing the cumulative mass enclosed within each radius $r$, aggregated across all MPI processes.

Notes

The method normalizes particle radii to a range of [0, 1] before mapping them to the grid of size nr. The final profile represents the total mass $M(<r)$.

Deprecated since version 1.0: This routine is legacy. It is recommended to use the more optimized grid-based methods defined in libgrid.

dens(r=None, nb=25, rm=50)¶

Compute the radial number density profile of the system.

Calculates the number of particles per unit volume in spherical shells, assuming a spherically symmetric distribution. The density is defined as $n(r) = dN / dV$.

Parameters

r (ndarray, optional) – Bin edges for the radial distance. If None, bins are created automatically using nb and rm. Default is None.
nb (int, optional) – Number of radial bins to use if r is not provided. Default is 25.
rm (float, optional) – Maximal radius for the profile if r is not provided. Default is 50.

Returns

r_mid (ndarray) – The midpoints of the radial bins.
density (ndarray) – The number density (count/volume) in each bin, aggregated across all MPI processes.

Notes

This routine calculates number density, not mass density. Particle masses are ignored.

Deprecated since version 1.0: This routine is legacy. It is recommended to use the more optimized grid-based methods defined in libgrid.

dmodes(nr=32, nm=16, rm=32)¶

Compute the azimuthal density Fourier modes of a disk model.

This method performs a Fourier decomposition of the surface density distribution as a function of the azimuthal angle $phi$. It identifies non-axisymmetric structures in the disk, such as bars (m=2) and spiral arms (m=2, 3, or 4).

Parameters

nr (int, optional) – Number of radial bins between 0 and rm. Default is 32.
nm (int, optional) – Number of Fourier modes to compute. Default is 16.
rm (float, optional) – Maximum radius ($R_{max}$) for the analysis. Default is 32.

Returns

Rs (ndarray) – The midpoints of the radial bins (shape nr).
m (ndarray) – The mode indices (integers from 0 up to nm-1).
m1 (ndarray) – Amplitude matrix of shape (nr, nm). m1[i, j] represents the strength of the $j$-th density mode at the $i$-th radius.
m2 (ndarray) – Phase matrix of shape (nr, nm). m2[i, j] represents the orientation (phase angle) of the $j$-th mode.

Notes

The method calculates the number of particles in azimuthal sectors for each radial annulus. A Fourier series is then fitted to this count-per-sector signal: $$Sigma(R, phi) = Sigma_0(R) [1 + sum A_m(R) cos(mphi - phi_m(R))]$$

Common Density Modes: * m = 1: Lopsidedness or an offset center of mass. * m = 2: Bars or two-armed grand-design spiral patterns. * m = 3, 4…: Multi-armed spiral features or higher-order perturbations.

Warning: As with zmodes, this routine requires a sufficient number of particles per bin to avoid Poisson noise dominating the signal.

histovel(nb=100, vmin=None, vmax=None, mode='n')¶

Compute the histogram of velocity magnitudes or radial velocities.

This method calculates the distribution of particle velocities across the system. It is useful for checking if a system has reached thermal equilibrium (e.g., matching a Maxwell-Boltzmann distribution) or for identifying high-velocity outliers and bulk radial flows.

nbint, optional
Number of bins for the histogram. Default is 100.

vminfloat, optional
Minimum velocity value for the binning range. If None, the global minimum of the selected velocity component is used. Default is None.

vmaxfloat, optional
Maximum velocity value for the binning range. If None, the global maximum of the selected velocity component is used. Default is None.

mode{‘n’, ‘r’}, optional
The velocity component to bin: * ‘n’ : Velocity norm (speed), $v = sqrt{v_x^2 + v_y^2 + v_z^2}$. * ‘r’ : Radial velocity in the $xy$-plane, $v_R =

rac{x v_x + y v_y}{sqrt{x^2 + y^2}}$.

Default is ‘n’.

hndarray: The frequency counts for each velocity bin, aggregated across MPI processes.
binsndarray: The bin edges used for the histogram.

The radial velocity mode (‘r’) specifically computes the planar radial component, which is standard for disk galaxy analysis. Global minimum and maximum values are synchronized across all MPI tasks before binning.

Deprecated since version 1.0: This routine is legacy and relies on direct particle binning. For grid-based velocity dispersion maps, use the routines defined in libgrid.

mdens(r=None, nb=25, rm=50)¶

Compute the radial mass density profile of the system.

Calculates the mass per unit volume in concentric spherical shells. Unlike dens, this method weights each particle by its mass to calculate the physical mass density $

ho(r) = dm / dV$.

rndarray, optional
Bin edges for the radial distance. If None, bins are created automatically using nb and rm. Default is None.

nbint, optional
Number of radial bins to use if r is not provided. Default is 25.

rmfloat, optional
Maximal radius for the profile if r is not provided. Default is 50.

r_midndarray
The midpoints of the radial bins.

densityndarray
The mass density ($

ho$) in each bin, aggregated across: all MPI processes.

This method assumes a spherically symmetric distribution and uses mass-weighted histogramming to account for varying particle masses.

Deprecated since version 1.0: This routine is legacy. It is recommended to use the more optimized grid-based methods defined in libgrid.

mr(r=None, nb=25, rm=50)¶

Compute the cumulative mass profile M(<r) of the system.

Calculates the total mass enclosed within a sphere of radius $r$, assuming a spherical distribution. This is achieved by summing particle masses in radial bins and computing the prefix sum (cumulative accumulation).

Parameters

r (ndarray, optional) – Radial bin edges. If None, bins are generated using nb and rm. Default is None.
nb (int, optional) – Number of radial bins to use if r is not provided. Default is 25.
rm (float, optional) – Maximum radius for the profile if r is not provided. Default is 50.

Returns

r (ndarray) – The radial bin edges used for the calculation.
m_enclosed (ndarray) – The cumulative mass enclosed within each corresponding radius, aggregated across all MPI processes.

Notes

The output $M(r)$ represents the integrated mass profile, which is fundamental for calculating circular velocities and gravitational potentials in spherical systems.

Deprecated since version 1.0: This routine is legacy. It is recommended to use the more optimized grid-based methods defined in libgrid.

msdens(r=None, nb=25, rm=50)¶

Compute the 2D projected mass surface density profile.

Calculates the mass per unit area in circular annuli on the $xy$-plane. This is the mass-weighted equivalent of sdens, representing the projected mass distribution $Sigma(r) = dm / dA$.

Parameters

r (ndarray, optional) – Bin edges for the radial distance in the projection plane. If None, bins are created using nb and rm. Default is None.
nb (int, optional) – Number of radial bins to use if r is not provided. Default is 25.
rm (float, optional) – Maximal radius for the profile if r is not provided. Default is 50.

Returns

r_mid (ndarray) – The midpoints of the radial bins.
surface_mass_density (ndarray) – The projected mass density ($Sigma$) in each annulus, aggregated across all MPI processes.

Notes

The calculation assumes a projection along the $z$-axis. It uses myNumeric.whistogram to sum particle masses within 2D concentric rings before normalizing by the ring area $A = pi(r_{out}^2 - r_{in}^2)$.

Deprecated since version 1.0: This routine is legacy. It is recommended to use the more optimized grid-based methods defined in libgrid.

sdens(r=None, nb=25, rm=50)¶

Compute the 2D surface number density profile (projected density).

Calculates the number of particles per unit area in circular annuli, typically assuming a projection onto the $xy$-plane. The density is defined as $Sigma(r) = dN / dA$.

Parameters

r (ndarray, optional) – Bin edges for the radial distance in the projection plane. If None, bins are created using nb and rm. Default is None.
nb (int, optional) – Number of radial bins to use if r is not provided. Default is 25.
rm (float, optional) – Maximal radius for the profile if r is not provided. Default is 50.

Returns

r_mid (ndarray) – The midpoints of the radial bins.
surface_density (ndarray) – The projected number density (count/area) in each annulus, aggregated across all MPI processes.

Notes

This routine calculates number density, not mass density. Particle masses are ignored. The calculation uses only the $x$ and $y$ coordinates, effectively projecting the system along the $z$-axis.

Deprecated since version 1.0: This routine is legacy. It is recommended to use the more optimized grid-based methods defined in libgrid.

sigma(r=None, nb=25.0, rm=50.0)¶

Compute the 3D velocity dispersion profiles and mean rotation curve.

Calculates velocity statistics in a cylindrical coordinate system $(R, heta, z)$. The method returns the radial, azimuthal, and vertical dispersions, alongside the mean azimuthal (rotation) velocity for a series of concentric annuli.

rarray_like, optional
Radial bin edges. If provided, the statistics are computed at the midpoints of these bins. Default is None.

nbint, optional
Number of radial bins to generate if r is not specified. Default is 25.

rmfloat, optional
Maximum radius for the profile if r is not specified. Default is 50.

rndarray
Midpoints of the radial bins.

srndarray
Radial velocity dispersion ($sigma_R$).

stndarray
Azimuthal velocity dispersion ($sigma_{ heta}$).

szndarray
Vertical velocity dispersion ($sigma_z$).

mtndarray
Mean azimuthal velocity ($langle v_{ heta}

angle$), representing

the rotation curve.

Warning: This routine assumes all particles have equal masses.

The transformation from Cartesian $(v_x, v_y)$ to cylindrical $(v_R, v_{ heta})$ is performed as: $$v_R =

rac{x v_x + y v_y}{sqrt{x^2 + y^2}}$$

$$v_{ heta} =

rac{x v_y - y v_x}{sqrt{x^2 + y^2}}$$

This method uses a Python loop over bins and selectc for particle filtering, which may be slow for very large datasets compared to vectorized histogram-based approaches.

Deprecated since version 1.0: This routine is legacy and relies on direct particle binning. For grid-based velocity dispersion maps, use the routines defined in libgrid.

sigma_vz(r=None, nb=25, rm=50)¶

Calculate the vertical velocity dispersion profile as a function of radius.

This method computes the 1D velocity dispersion along the $z$-axis ($sigma_{v_z}$) within concentric cylindrical annuli (bins) on the $xy$-plane. It is an essential diagnostic for assessing the vertical kinematics and dynamical heating of a disk system.

rarray_like, optional
Pre-defined radial bin edges for the $xy$-plane. If None, bins are generated automatically from 0 to rm. Default is None.

nbint, optional
Number of radial bins to create if r is not provided. Default is 25.

rmfloat, optional
The maximum radius ($R_{max}$) to consider for the profile if r is not provided. Default is 50.

rndarray
The midpoints or edges of the radial bins used for the histogram.

hndarray
The vertical velocity dispersion ($sigma_{v_z}$) in each radial bin.

The computation is performed via the internal Histo method using mode=’svz’. This mode typically calculates the standard deviation of the $v_z$ component of particles falling within each cylindrical shell: $sigma_{v_z} = sqrt{langle v_z^2

angle - langle v_z angle^2}$.

Deprecated since version 1.0: This routine is legacy and relies on direct particle binning. For grid-based velocity dispersion maps, use the routines defined in libgrid.

sigma_z(r=None, nb=25, rm=50)¶

Compute the vertical velocity dispersion profile ($sigma_z$) as a function of radius.

This method calculates the 1D velocity dispersion along the $z$-axis within concentric cylindrical annuli on the $xy$-plane. This is a key diagnostic for measuring the “vertical heating” or thickness of a galactic disk.

rarray_like, optional
Bin edges for the radial distance in the $xy$-plane. If None, bins are automatically generated using nb and rm. Default is None.

nbint, optional
Number of radial bins to use if r is not provided. Default is 25.

rmfloat, optional
The maximum radius ($R_{max}$) for the profile if r is not provided. Default is 50.

r_midndarray
The midpoints of the radial bins where the dispersion was evaluated.

sigma_zndarray
The vertical velocity dispersion values ($sigma_z = sqrt{langle v_z^2

angle - langle v_z angle^2}$)

for each bin.

The computation is performed via the internal Histo method using mode=’sz’, which handles the statistical aggregation and MPI communication.

Deprecated since version 1.0: This routine is legacy and relies on direct particle binning. For grid-based velocity dispersion maps, use the routines defined in libgrid.

zmodes(nr=32, nm=16, rm=32)¶

Perform a vertical Fourier decomposition to identify disk bending modes.

This method analyzes the vertical structure of a disk by decomposing the mean vertical position ($langle z

angle$) as a function of the azimuthal

angle ($ heta$) into Fourier modes for different radial bins. This is the standard approach for identifying “warps” (m=1), “corrugations”, or “U-shaped” (m=0) bending modes in galactic disks.

nrint, optional: Number of radial bins between 0 and rm. Default is 32.
nmint, optional: Number of Fourier modes to compute. Default is 16.
rmfloat, optional: Maximum radius ($R_{max}$) for the analysis. Default is 32.

Rsndarray: The midpoints of the radial bins (shape nr).
mndarray: The mode indices (integers from 0 up to nm-1).
m1ndarray: Amplitude matrix of shape (nr, nm). m1[i, j] is the amplitude of the $j$-th mode at the $i$-th radius.
m2ndarray: Phase matrix of shape (nr, nm). m2[i, j] is the phase of the $j$-th mode at the $i$-th radius.

The method operates in two steps: 1. It divides the disk into concentric annuli and then further

subdivides each annulus into azimuthal sectors to compute the mean vertical height $langle z

angle( heta)$.

It applies a Fourier transform to this $langle z

angle( heta)$

signal to extract the power and phase of different vertical modes.

Common Vertical Modes: * m = 0: Integral sign / Symmetric bending. * m = 1: Warp (the disk tips up on one side and down on the other). * m = 2: S-shaped or “bowl” modes.

zprof(z=None, r=2.5, dr=0.5, nb=25, zm=5.0)¶

Compute the vertical density profile at a specific radial distance.

This method extracts a cylindrical annulus (ring) of width dr at radius r and calculates the volume density of particles as a function of height z. It is commonly used to measure the vertical scale height of a disk component and to determine if the vertical distribution follows an exponential or $ ext{sech}^2$ law.

zarray_like, optional
Pre-defined bin edges for the vertical height $z$. If None, bins are generated automatically from -zm to zm. Default is None.

rfloat, optional
The central radius of the cylindrical cut in the $xy$-plane. Default is 2.5.

drfloat, optional
The radial width of the annulus ($Delta R$). Default is 0.5.

nbint, optional
Number of vertical bins to use if z is not provided. Default is 25.

zmfloat, optional
The maximum vertical extent to consider. The profile will range from $-zm$ to $+zm$. Default is 5.0.

zndarray
The lower edges of the vertical bins.

profndarray
The volume density ($

ho$) in each bin, normalized by the

volume of the cylindrical shell segment.

Warning: This routine assumes all particles have equal masses. If the simulation contains multi-mass particles, the resulting profile will represent number density rather than mass density.

The volume of each bin segment is calculated as: $V = pi (r_{out}^2 - r_{in}^2) imes Delta z$

Deprecated since version 1.0: This routine is legacy and relies on direct particle binning. For grid-based velocity dispersion maps, use the routines defined in libgrid.

Unitless quantities methods (deprecated)¶

Previous topic

Next topic

This Page