Skip to content

salvus.flow.solver

salvus.flow.solver salvus flow solver

Runtime configuration object for the in-process solver.

Classes

NewtonianNoiseOutput

class NewtonianNoiseOutput(builtins.object):
    def __init__(
        self,
        test_masses: tuple[tuple[float, float, float], ...],
        sampling_interval_in_time_steps: int = 1,
        filename: str = "newtonian_noise.h5",
        method: str = "projection",
        cavity_density: float = 0.0,
        projection_order: int | None = None,
    ) -> None: ...

Request on-the-fly Newtonian-noise output from the in-process solver.

Computes the Newtonian (gravitational) acceleration perturbation at a set of test-mass positions during time stepping, in the Lagrangian formulation - no volume output is ever stored. Pass an instance via the output argument of Solver:

import salvus.namespace as sn

sn.functions.run(
    site_name=sn.solver.Solver(
        backend="python",
        output=sn.solver.NewtonianNoiseOutput(
            test_masses=[[0.0, 0.0, 0.0], [50.0, 0.0, 0.0]],
            sampling_interval_in_time_steps=5,
        ),
    ),
    input_file=w,
    output_folder="output",
)
# The result is `output/newtonian_noise.h5`.

The results are delivered as a file, so an output_folder is required.

The integration region is taken from the mesh’s region_of_interest elemental field if present - the same field the command-line solver Newtonian-noise postprocessing workflow uses - and covers the whole mesh otherwise. Every test mass must lie outside the integration region (the kernel is singular at the test mass), so the field must carve out a cavity around all of them.

All test masses are evaluated at every sampled time step. The integration operator is rebuilt per sample, one test mass at a time, so memory stays small regardless of their number; the per-sample compute grows linearly with it, which is cheap as long as samples are much rarer than time steps - the intended regime.

Currently limited to 3-D isotropic elastic simulations, on every backend ("python", "cpu", "cuda").

Cost, measured on an order-4 mesh (default projection_order, 6) with a 208-element integration region at sampling_interval_in_time_steps=1 (the worst case; a larger interval divides the sampler’s cost directly):

backend time loop + collocation + projection
cuda 0.365 ms/step 0.713 0.869
cpu (1 core) 60.2 ms/step 60.9 70.2

The cavity-wall correction adds no measurable cost.

Parameters
  • test_masses tuple[tuple[float, float, float], ...] — The positions at which the Newtonian acceleration is computed, in meters: anything array-like of shape [n_tm, 3] (a single [3] location is also accepted). Normalized to nested tuples, so the configuration object stays immutable and hashable.
  • sampling_interval_in_time_steps int = 1 — Record the Newtonian acceleration every N time steps.
  • filename str = 'newtonian_noise.h5' — Name of the HDF5 output file, written into the run’s output folder. A bare file name without path components; receivers.h5 and meta.json are reserved for the standard output files every run writes.
  • method str = 'projection' — "projection" (default) integrates on a Gauss-Legendre rule per element, with projection_order points per direction. "collocation" integrates on the mesh’s own GLL quadrature, which under-integrates the kernel’s curvature close to a test mass: ~1e-4 relative on a near-field wavefield around a small cavity, against ~1e-8 for "projection" at its order-4 default of 6 points.
  • cavity_density float = 0.0 — Density (kg/m^3) filling the cavity carved out of the integration region around the test masses. 0.0 (the default) is a vacuum; a nonzero value adds the cavity-wall surface correction (see ng_salvus.io.newtonian_noise). With method="collocation" this is backend="python" only.
  • projection_order int | None = None — Gauss-Legendre points per direction per element (and per cavity-wall facet) for method="projection". None (the default) is the simulation’s polynomial order + 2, one more than its GLL nodes: at order + 1 the error on a small cavity is ~20x larger, and a higher order gains little.
Attributes
test_masses_array npt.NDArray

The test-mass positions as an array, shape [n_tm, 3].

Solver

class Solver(builtins.object):
    def __init__(
        self,
        backend: typing.Literal["python", "cpu", "cuda"] = "python",
        dtype: typing.Literal["float32", "float64"] = "float64",
        execution_policy: bindings.ExecutionPolicy = default,
        time_integrator: typing.Literal[
            "newmark_beta", "pefrl"
        ] = "newmark_beta",
        courant_number: float | None = None,
        output: tuple[NewtonianNoiseOutput, ...] = (),
        solution_order: int | None = None,
    ) -> None: ...

Configure the in-process solver at runtime.

An instance of this class can be passed anywhere a site_name string is accepted, e.g. in salvus.flow.functions.run. The simulation then executes in-process instead of being submitted to a configured site:

import salvus.namespace as sn

sn.functions.run(
    site_name=sn.Solver(backend="python"),
    input_file=w,
    output_folder="output",
)
Parameters
  • backend typing.Literal['python', 'cpu', 'cuda'] = 'python' — The compute backend. "python" (the default) is the reference implementation, driving ng_salvus.time_integrators.solve’s Python step loop. "cpu" runs natively through the session machinery (ng_salvus.operators.sessions.CpuSession, matching the solver’s own name for this backend): forward simulations via time_integrators.solve_forward_through_sessions, adjoints via solve_adjoint_through_sessions. Solver-side outputs (output below) are attached as native samplers on both single- and multi-block runs. "cuda" runs through CudaSession (ng_salvus.operators.sessions.CudaSession): a single- block, NewmarkBeta acoustic or elastic forward or adjoint, with the same native sampler support for solver-side outputs — anything past that scope (a mixed-physics mesh, "pefrl") refuses loudly rather than silently falling back to another backend. Requires solution_order.
  • dtype typing.Literal['float32', 'float64'] = 'float64' — Floating point precision of the computation.
  • execution_policy bindings.ExecutionPolicy = <factory> — The rank/thread topology to run under.
  • time_integrator typing.Literal['newmark_beta', 'pefrl'] = 'newmark_beta' — The time integration scheme.
  • courant_number float | None = None — Courant number used to derive the time step. None means the time integrator’s default.
  • output tuple[NewtonianNoiseOutput, ...] = () — Additional solver-side outputs computed during the run. A single output request or any sequence of them, normalized to a tuple; NewtonianNoiseOutput is the only request type so far. Distinct from the simulation object’s own output section: these are runtime capabilities of the in-process solver, not part of the input file.
  • solution_order int | None = None — The wavefield basis’s own solution order — NOT the mesh’s own geometric order (Mesh.model_order), though the solver requires the two equal today. Required for backend="cuda" — unlike "cpu", CudaSession has no way to derive this from the mesh’s own DOF count and fails loud if it disagrees with the geometry. Ignored for every other backend.
Attributes
newtonian_noise_output NewtonianNoiseOutput | None

The run’s NewtonianNoiseOutput request, or None.