Numerical settings

Every numerical setting of the package is a field of pianistpy.Settings. The tables below list each field, its value under the default settings and under the quick settings (Accuracy), and what the field controls. The fields fall in five groups, one table each: inversion, truncation, sampling, observables and losvd.

An override of a field, such as pp.Settings(inversion={"n_nodes": 256}), raises InputError when the group or the field’s name is unknown. An override also raises InputError when the value has the wrong type, or when the value is not positive for a field that must be positive.

inversion

Field	Default	Quick	What it controls
n_nodes	500	same	The number of Gauss-Legendre nodes of the integral that inverts the density into the distribution function.
n_grid_rows	1000	same	The number of energies in the middle zone of the inversion’s energy grid, where the energies are spaced linearly.
n_grid_tail_rows	3000	same	The number of energies in each of the two end zones of the inversion’s energy grid, where the energies are spaced logarithmically toward the grid’s floor and toward the grid’s top.
grid_tail_extent	0.03	same	The width of each end zone of the inversion’s energy grid, as a fraction of the central potential.
table_nodes_per_decade	50	same	The number of energies per decade below the floor of the inversion’s energy grid, down to the floor of the distribution function’s table.
n_floor_nodes	240	same	The number of Gauss-Legendre nodes, in ln P, of the integral that completes the distribution function below the table’s floor; a third of the nodes, and at least 40 nodes, lie near the floor.

truncation

Field	Default	Quick	What it controls
n_source_nodes	500	same	The number of Gauss-Legendre nodes in each of the two intervals of the quadrature that computes the auxiliary density on the source grid.
n_source_rows	12000	same	The number of potential values of the source grid.
n_source_tail_rows	3000	same	The number of potential values in each logarithmic tail of the source grid, toward the grid’s floor and toward the grid’s top; each tail holds at most a third of the source grid’s potential values.
source_tail_extent	0.03	same	The largest width of each tail of the source grid, as a fraction of the grid’s top; the width used is at most a hundredth of the grid’s top.
source_tail_floor	1.20401e-08	same	The smallest start of the source grid’s lower tail and the smallest width of the source grid’s upper tail, as fractions of the grid’s top.
quadrature_split	0.9	same	The fraction of the potential at which the first interval of the source quadrature ends and the second interval begins.
quadrature_stretch	2	same	The power k of the map Q = P - u^k on the second interval of the source quadrature, where the exponent of the quadrature’s kernel is not negative.
ode_rtol	1e-11	same	The relative tolerance of the integration of Poisson’s equation.
ode_atol	1e-11	same	The absolute tolerance of the integration of Poisson’s equation.
n_rows_inner	500	same	The number of radii of the Poisson solve’s grid inside the inner zone.
n_rows_outer	59500	same	The number of radii of the Poisson solve’s grid outside the inner zone.
log10_r_min	-9	same	The base-10 logarithm of the innermost radius of the Poisson solve, in internal length units.
log10_r_max	12	same	The base-10 logarithm of the outermost radius of the Poisson solve, in internal length units. A computation raises the outermost radius until the potential at the outermost radius is below half the floor, and the result records the value used.
continuation_start	0.01	same	The fraction of the central potential below which the outermost radii of a truncated model are solved again on a grid geometric in R_t - r, where R_t is the truncation radius.
continuation_rows_per_decade	1200	same	The number of radii per decade of R_t - r in the solve toward the truncation radius R_t.
continuation_floor_fraction	0.02	same	The potential at the outermost radius of the solve toward the truncation radius, as a fraction of the floor.
profile_bin_decades	0.1	same	The width, in decades of the potential, of each bin in which the profile’s radii are counted.
profile_rows_per_decade	1000	same	The smallest number of radii per decade of the potential, and per decade of the depth, that the profile keeps at the profile’s two ends; the profile’s fills supply the other radii.

sampling

Field	Default	Quick	What it controls
n_rows	512	same	The number of potential values of the velocity table at the start of the table’s refinement; the number doubles until the table’s own error across potential values is below row_error_goal or until the number reaches n_rows_max.
n_rows_max	4075	same	The largest number of potential values of the velocity table; the table’s refinement stops at n_rows_max potential values.
n_nodes	2048	512	The number of nodes at each potential value of the velocity table.
n_velocity_intervals	200	same	The number of intervals in the scaled velocity over which the velocity distribution is integrated at each potential value of the velocity table.
n_gauss_legendre	16	8	The number of Gauss-Legendre nodes of each panel of the velocity integrals.
panels_per_decade	8	same	The number of panels per decade of the local variable where the velocity integrals refine toward the two ends of the velocity range at one potential value and inside each interval.
velocity_low_refined	1e-09	same	The smallest scaled velocity that the velocity integrals refine in panels; below that velocity, the density follows the density’s power law in the velocity and is integrated in closed form.
edge_refined	1e-12	same	The distance from the edge of the velocity range, relative to the edge, down to which the velocity integrals refine in panels; closer to the edge, the distribution function’s form below the distribution function’s table is integrated in closed form.
radius_edge_refined	1e-10	same	The smallest fraction of the mass beyond a radius that the radius table of a model with a sharp edge resolves in nodes; for smaller fractions, the mass follows the mass’s power law in the distance from the edge.
n_radius_nodes	2048	same	The number of nodes of the radius table.
n_angle_nodes	1024	same	The number of nodes of each half of the angle table, spaced uniformly in the logarithm of the cumulative probability from the half’s end.
draw_block	262144	same	The number of particles drawn at once. A draw runs over blocks of draw_block particles, so the draw’s working memory, above the memory of the drawn particles, is the memory of one block: about 0.75 kB per particle, or about 0.2 GB for \(2^{18}\) particles. The drawn particles do not depend on draw_block.
row_error_goal	1e-06	0.0001	The error across the potential values of the velocity table at which the table’s refinement stops: the number of potential values doubles until the table’s own error is below row_error_goal or until the number reaches n_rows_max.
tail_mass_min	1e-18	same	The smallest cumulative probability tabulated at either end of a table. The smallest nonzero value of a uniform random double is \(2^{-53}\), which is above tail_mass_min, so a draw never reads beyond the tabulated range.

observables

Field	Default	Quick	What it controls
n_radii	10000	500	The number of projected radii of the projection table before the table’s check between projected radii adds projected radii; the projected radii are spaced logarithmically from the innermost radius of the profile to the edge.
profile_tolerance	1e-07	1e-06	The relative error of sigma_r at which radii stop being added to the radial dispersion’s profile: sigma_r at the midpoint of every interval between the profile’s radii is read within profile_tolerance. The default value, \(10^{-7}\), is a tenth of \(10^{-6}\): the profile’s share of the error of the quantities projected from the profile.
n_profile_start	100	same	The number of radii, spaced logarithmically from the innermost radius of the profile to the edge, with which the radial dispersion’s profile starts before radii are added to meet profile_tolerance.
n_jeans_nodes	500	same	The number of Gauss-Legendre nodes of the Jeans integral of the radial dispersion at one radius, as the superposition of components computes the radial dispersion. The observables’ profile does not use n_jeans_nodes: the profile sums panels between the profile’s radii and doubles each panel’s nodes until sigma_r changes by less than profile_tolerance.
n_projection_nodes	500	same	The number of Gauss-Legendre nodes of each line-of-sight integral of the surface density and of the projected dispersion.
n_aperture_nodes	100	same	The smallest number of Gauss-Legendre nodes of each panel of an aperture’s radial integral.
aperture_nodes_per_decade	8	same	The number of nodes per decade of projected radius of a panel of an aperture’s radial integral: a panel spanning d decades takes aperture_nodes_per_decade times d nodes, rounded up to a multiple of 20, if that number exceeds n_aperture_nodes.
rows_route	kernel	same	The computation of the angle rule of the line-of-sight velocity distributions: “kernel” computes the angle rule with JAX, and “numpy” computes the angle rule with NumPy, as a reference.
n_velocity_angle_nodes	16	same	The number of Gauss-Legendre nodes of each panel of the angle integral of the local velocity distribution (pdf_v), in t = cos(eta).
n_velocity_angle_panels	16	8	The number of panels of the angle integral of the local velocity distribution (pdf_v) graded toward each end of each of the integral’s intervals, and the number of panels of the velocity integral of the distribution’s norm and second moment graded toward each break of that velocity integral.
velocity_tolerance	1e-06	0.0001	The bound on the change of the local velocity distribution (pdf_v) when the nodes of the distribution’s angle rule double: the nodes double, at most three times, until the change is below velocity_tolerance.

losvd

Field	Default	Quick	What it controls
rows_per_decade	55	20	The number of base projected radii per decade of the table of line-of-sight velocity distributions, from the innermost radius of the profile.
n_energy_nodes	8	same	The number of Gauss-Legendre nodes of each panel of the energy integral at one node of the table.
n_floor_layers	4	2	The number of Gauss-Legendre panels of the energy integral graded toward K = 0, where the DF’s rule below its table takes over.
energy_layer_ratio	0.2	same	The ratio of the widths of successive graded panels of the energy integral.
n_angle_nodes	64	same	The largest number of Gauss-Legendre nodes of the angle integral of an L factor at one node of the table.
n_sightline_nodes	12	8	The number of Gauss-Legendre nodes of each panel of the line-of-sight integral.
n_sightline_panels	8	same	The number of panels of each interval of the support along the line of sight.
sightline_panels_refined	6	same	The number of doublings of the line-of-sight panels allowed before a projected radius is recorded as not converged.
sightline_layer_ratio	0.3	same	The ratio of the widths of successive line-of-sight panels graded toward the axis.
n_sightline_layers	4	same	The number of line-of-sight panels graded toward the axis that each doubling adds.
n_crossing_scan	2001	same	The number of points of the scan for the positions where the angular momentum vanishes.
n_cumulative_nodes	200001	same	The number of nodes of each of the three branches of the table of the distribution function’s cumulative integral.
n_velocity_nodes	16	8	The number of Gauss-Legendre nodes of each velocity sub-panel at one projected radius.
velocity_layer_ratio	0.3	same	The ratio of the widths of successive velocity sub-panels graded toward a break of the distribution.
n_velocity_layers_zero	12	same	The number of velocity sub-panels graded toward zero velocity.
n_velocity_layers_break	8	same	The number of velocity sub-panels graded toward each break of the distribution at one projected radius.
n_break_scan	4001	1001	The number of points of the coarse scan for a break of the distribution in velocity.
n_break_zooms	4	same	The number of successive refinements of the scan for a break of the distribution in velocity.
n_bisections	60	same	The number of bisections that locate an edge of the support, or a root, along a line of sight.
n_radius_break_layers	16	same	The number of projected radii added toward each projected radius at which the table’s layout changes.
n_radius_break_bisections	40	same	The number of bisections in projected radius that locate a change of the table’s layout.
n_radius_break_samples	3	same	The number of samples inside each interval between base projected radii at which a change of the table’s layout is sought.
n_edge_samples	10	same	The number of samples beyond the last base projected radius toward the end of the profile.
n_edge_layers	16	same	The number of projected radii added toward the end of the table.
n_stencil_rows	8	same	The number of tabulated projected radii that the interpolation between the table’s projected radii reads.
n_stencil_test_rows	8	same	The number of tabulated projected radii of the second interpolation, whose estimate checks the table’s interpolation.
n_block_elements	25000	same	The number of elements (node pairs times energy nodes times angle nodes) computed in one block, which bounds the memory of the computation at one projected radius.
innermost_read_radius	0	same	The smallest projected radius at which the table will be read, in the model’s internal length unit. The table starts at the last base projected radius inside the radius whose disk holds \(10^{-6}\) times the projected mass inside innermost_read_radius, and a read inside the table’s first projected radius raises InputError. The value 0 keeps the table’s full depth, from the innermost radius of the profile.
outer_mass_share	1e-06	same	The share of the total projected mass that may lie beyond the table’s last projected radius. The table ends at the first base projected radius beyond the radius outside which outer_mass_share of the projected mass lies, and a read beyond the table’s last projected radius raises InputError. The value 0 keeps the table out to the model’s edge.

Settings levels: default, quick. A field is overridden by its group and its name, for example pp.Settings(inversion={'n_nodes': 800}). A result computed with an overridden field records that its settings are custom, and lists the fields that differ from the settings level.