Tune

The MultilevelSummation.Tune submodule provides programmatic hyperparameter sweeps. Given a system and an absolute reference energy (e.g. from MultilevelSummation.Reference), it iterates over (h, a, L) combinations and returns a table of SweepResult rows so the user can inspect them and pick parameters in their own code.

using MultilevelSummation
using MultilevelSummation.Tune

U_ref = Tune.ewald_reference(positions, charges, cell)
rows  = Tune.sweep(positions, charges, cell, periodic;
                   reference  = U_ref,
                   h_values   = (0.5, 1.0, 2.0),
                   a_values   = (2.0, 4.0, 8.0),
                   L_strategy = :all)

best  = Tune.recommend(rows; max_rel_err = 1e-3)
front = Tune.pareto_front(rows)

The shipped tuning/ scripts (tune_NaCl.jl for a perturbed rock-salt supercell, tune_H2O.jl for a TIP3P-like water box) are thin callers of the same API on realistic test systems; their CSV output is the canonical way to explore accuracy-vs-cost trade-offs on a given problem class.

Result type

MultilevelSummation.Tune.SweepResult — Type

SweepResult{T}(h, a, L, n_grid, energy, rel_err, t_msm)

One row of a sweep result. Fields:

h::T — finest grid spacing.
a::T — short-range cutoff.
L::Int — number of MSM levels.
n_grid::Int — cell_axis_length / h (assumed isotropic).
energy::T — MSM energy.
rel_err::T — |energy − reference| / |reference|.
t_msm::Float64 — wall-clock time of the timed call, in seconds.

source

Sweep + helpers

MultilevelSummation.Tune.sweep — Function

sweep(positions, charges, cell, periodic;
      reference::Real,
      basis = CubicC1{T}(),
      h_values = (0.5, 1.0, 2.0),
      a_values = (2.0, 4.0, 8.0),
      L_strategy::Symbol = :max,
      warmup::Bool = true) -> Vector{SweepResult{T}}

Iterate msm_energy(positions, charges, cell, periodic, calc) over all valid (h, a, L) settings drawn from h_values × a_values and a level range determined by L_strategy:

:max — only the largest valid L per h.
:all — L = 2 … L_max.

A combination is skipped if the cell axis isn't an integer multiple of h or if no L ≥ 2 has 2^{L-1} dividing n_grid = cell/h.

Each combination is JIT-warmed up once (warmup=true) before timing.

The cell is assumed cubic (isotropic) for the n_grid = cell/h step; this matches how the rest of the package picks the grid hierarchy.

source

MultilevelSummation.Tune.pareto_front — Function

pareto_front(results::AbstractVector{SweepResult{T}}) -> Vector{SweepResult{T}}

Return the subset of results that is Pareto-optimal on the (rel_err, t_msm) plane, sorted by ascending rel_err.

An entry r is dominated if there exists another entry r' with both rel_err(r') ≤ rel_err(r) and t_msm(r') ≤ t_msm(r) and at least one strict.

source

recommend(results::AbstractVector{SweepResult}; max_rel_err::Real) -> SweepResult

Return the fastest entry in results whose rel_err ≤ max_rel_err. Throws ArgumentError if no entry satisfies the bound.

source

MultilevelSummation.Reference.ewald_reference — Function

ewald_reference(positions, charges, cell; tol = 1e-9) -> Real

Auto-tuned convenience wrapper: pick (α, R_cut, k_cut) from the cell extent and the prescribed truncation tolerance tol, then call ewald_energy.

Selection rule:

R_cut = min(box/2 − 0.5, 14)
α     = √(−log tol) / R_cut
k_cut = 2 α √(−log tol)

Returns the total Ewald energy. Used by Tune.run_system_sweep as the absolute reference against which MSM sweep results are compared.

source