Bases and mappings

UniformBasisSpec(family; xmin, xmax, spacing=1.0)

Recipe for building a uniform full-line gausslet basis over [xmin, xmax].

MappedUniformBasisSpec(family; count, mapping, reference_spacing=1.0)

Recipe for building a full-line gausslet basis from one global coordinate map applied to a uniform reference-coordinate gausslet array.

The basis centers in reference space are

-(count-1)/2, ..., +(count-1)/2

times reference_spacing, then mapped into physical space.

HalfLineBasisSpec(family; xmax, reference_spacing=1.0, tails=6,
                  mapping=IdentityMapping())

Recipe for building a boundary-correct half-line gausslet basis on [0, xmax] or, when mapped, over approximately the corresponding physical range.

RadialBasisSpec(family; rmax, mapping, reference_spacing=1.0, tails=6,
                odd_even_kmax=6, xgaussian_count=2, xgaussians=nothing)
RadialBasisSpec(family; count, mapping, reference_spacing=1.0, tails=6,
                odd_even_kmax=6, xgaussian_count=2, xgaussians=nothing)

Recipe for building a radial gausslet basis for the reduced radial function u(r) = r R(r).

By default this uses the current preset two-XGaussian supplement from recommended_xgaussians(2). Advanced users can override that by passing an explicit xgaussians vector.

recommended_xgaussians(count::Integer = 2)

Return the current preset near-origin XGaussian supplement used for the radial front door.

The current preset family is:

• count = 0: no xgaussians
• count = 1: [XGaussian(alpha = 0.0936)]
• count = 2: [XGaussian(alpha = 0.0936), XGaussian(alpha = 0.0236)]

These are the published paper-parity widths for the K = 6 two-xgaussian radial-gausslet construction. Advanced users can still pass explicit xgaussians vectors when they want a different supplement.

build_basis(spec::UniformBasisSpec)
build_basis(spec::HalfLineBasisSpec; grid_h=nothing, refine_grid_h=true)
build_basis(spec::RadialBasisSpec; grid_h=nothing, refine_grid_h=true)

Build the concrete basis described by spec.

This is the main public entry point for turning a basis recipe into an actual basis object. The returned type depends on spec:

• UniformBasisSpec -> UniformBasis
• MappedUniformBasisSpec -> MappedUniformBasis
• HalfLineBasisSpec -> HalfLineBasis
• RadialBasisSpec -> RadialBasis

Typical usage is:

spec = RadialBasisSpec(:G10; rmax = 30.0, mapping = AsinhMapping(c = 0.1, s = 0.2))
rb = build_basis(spec)

build_basis(spec::MappedUniformBasisSpec)

Build the concrete globally mapped full-line basis described by spec.

build_basis(spec::HalfLineBasisSpec; grid_h=nothing, refine_grid_h=true)

Build the concrete half-line basis described by spec.

grid_h controls the internal construction-grid spacing used while orthonormalizing and localizing the basis. It is a build-time control, not part of HalfLineBasisSpec. When refine_grid_h=true, construction starts from the supplied or default grid_h and internally halves it until an overlap check on a finer reference grid is acceptable.

build_basis(spec::RadialBasisSpec; grid_h=nothing, refine_grid_h=true)

Build the concrete radial basis described by spec.

grid_h controls the internal construction-grid spacing used while building and localizing the reference-coordinate basis. It is a build-time control, not part of RadialBasisSpec. When refine_grid_h=true, construction starts from the supplied or default grid_h and internally halves it until an overlap check on a finer reference grid is acceptable.

IdentityMapping()

Identity coordinate mapping with uofx(map, x) == x.

AsinhMapping(; c, s, tail_spacing=10.0)
AsinhMapping(; a, s, tail_spacing=10.0)

Forward mapping

u(x) = x / tail_spacing + asinh(x / a) / s

The linear tail term is built in for this mapping. The keyword a is the direct parameter in the asinh term. The keyword c is the derived near-origin control with

c = a * s

so AsinhMapping(c=c0, s=s0) is equivalent to AsinhMapping(a=c0 / s0, s=s0).

fit_asinh_mapping_for_extent(; npoints, xmax, reference_spacing=1.0, tail_spacing=10.0)

Build the symmetric one-parameter AsinhMapping(c=s, s=s) used in the current working mapped ordinary Cartesian hydrogen path, choosing s so that the outer basis centers of an odd-count full-line basis land at x = ±xmax.

This helper is intentionally narrow:

• odd npoints
• full-line basis centered at the origin
• reference centers spaced by reference_spacing
• the single-parameter family AsinhMapping(c=s, s=s, tail_spacing=...)

The endpoint condition is

u(xmax) = ((npoints - 1) / 2) * reference_spacing

which gives the closed-form choice

s = asinh(xmax) / ( ((npoints - 1) / 2) * reference_spacing - xmax / tail_spacing ).

This helper should be read as a narrow current working choice, not as a claim that AsinhMapping or the present coupled c,s tuning is already final for the ordinary mapped branch.

fit_asinh_mapping_for_strength(; s, npoints, xmax, reference_spacing=1.0, tail_spacing=10.0)

Build an AsinhMapping(a=a_fit, s=s, tail_spacing=tail_spacing) with a fixed distortion strength s, choosing a_fit so that the outer centers of an odd full-line basis land at x = ±xmax.

This is the fixed-extent companion to fit_asinh_mapping_for_extent. It is intentionally narrow:

• odd npoints
• full-line basis centered at the origin
• fixed s
• a chosen by a one-dimensional solve
• the endpoint condition

u(xmax) = ((npoints - 1) / 2) * reference_spacing

This is again a narrow current working helper for mapped ordinary studies, not a claim that the present mapping family or c,s heuristics are settled.

HybridMappedOrdinaryBasis1D

Hybrid ordinary one-dimensional basis built from a mapped ordinary backbone plus a small explicit set of added core Gaussians.

This is the current practical ordinary-branch object for the friendlier hybrid/core-supported regime. It keeps the mapped gausslet backbone visible, but augments it with centered Gaussian support near the origin.

hybrid_mapped_ordinary_basis(
    basis::MappedUniformBasis;
    core_gaussians,
    backend = :pgdg_localized_experimental,
)

Build a hybrid one-dimensional ordinary basis from a mapped ordinary backbone plus a small explicit Gaussian supplement.

The backbone comes from the chosen mapped ordinary backend. The added core_gaussians can be either:

• a small explicit Gaussian list
• a LegacyAtomicGaussianSupplement centered atomic supplement

In both cases the active seed is built from explicit primitive Gaussians, with any legacy shell contraction applied on the added channel before the final overlap cleanup and COMX-style localization step.

At present, passing a LegacyAtomicGaussianSupplement with non-s shell content is rejected explicitly. A true active p supplement needs an explicit 3D shell route rather than the current centered separable 1D supplement path.

Typical usage is:

hybrid = hybrid_mapped_ordinary_basis(
    basis;
    core_gaussians = [Gaussian(center = 0.0, width = 0.2)],
)