SDF-MPNEO vNext

SDF-MPNEO vNext is the mesh-free-first electrothermal surrogate runtime. The core model uses geometry-local conductor/surface/volume quadrature, dense or matrix-free correctness backends, structure-preserving neural FAST artifacts, and continuous thermal Green/interface evolution. It does not require a fixed world voxel/FEM mesh or a finite thermal/world truncation box.

The current vNext branch supports arbitrary-pose finite-cross-section superelliptic spiral coils, strictly nested or mutually disjoint superquadric material regions, homogeneous isotropic or tensor-electric backgrounds, piecewise-homogeneous isotropic or tensor-electric package materials, continuous conductor/package/background loss fields, and time-dependent thermal queries. REFERENCE, FAST, and CERTIFIED remain separate execution paths so neural inference never silently replaces the correctness backend.

Install

Python 3.10+ is required.

pip install -e ".[dev]"

For neural FAST artifacts:

pip install -e ".[dev,neural]"

For the one-click PyQt training console:

pip install -e ".[dev,neural,gui]"

The NumPy/SciPy REFERENCE and CERTIFIED paths do not require PyTorch.

One-click cached / resumable training

The root run.py is the main vNext training configuration and launch entry. Edit CONFIG in that file, then run:

python run.py

The default mode opens a nonblocking PyQt6/pyqtgraph console. Training runs in an independent QProcess and metrics are tailed by a QThread, so correctness teacher solves and CUDA training do not block the UI. The window provides start/resume, pause, resume and safe stop controls together with port/spatial loss curves and teacher-cache progress.

Headless training uses the same configuration:

python run.py --mode train

Teacher truth is stored in a content-addressed cache. Keeping the sampler, teacher and truth parameter space unchanged reuses existing deterministic sample shards; changing sample count only generates missing shards. Network, optimizer, device and GUI changes do not invalidate teacher data. Port and spatial model checkpoints store optimizer/model/RNG/batch position state for safe continuation after a stop.

See docs/VNEXT_TRAINING_GUI.md for the full configuration, cache identity and resume semantics.

Scene model

The main objects are:

• SuperellipseSpiral + ConductorMaterial + CoilObject;
• optional SuperquadricPackageGeometry + material + PackageObject;
• arbitrary independent RigidPose values for coils and packages;
• a homogeneous background material;
• optional strictly nested or mutually disjoint material regions.

Isotropic electric materials may use HomogeneousMedium, IsotropicMaterial, DebyeMaterial, MultiDebyeMaterial, TabulatedMaterial, or another passive frequency-response implementation. Tensor-electric regions use TensorElectricMaterial, with an SPD relative-permittivity tensor and a PSD conductivity tensor whose principal axes are expressed in the containing region frame. Package tensors therefore rotate with package pose, while a background tensor is expressed in world axes.

The tensor-electric backend is a piecewise-homogeneous electric transmission model. It is not a general continuously varying tensor VIE solver.

REFERENCE / FAST / CERTIFIED

MeshfreeVNextSystem is the common runtime:

from sdfmpneo_vnext import MeshfreeVNextSystem

system = MeshfreeVNextSystem(
    port_artifact,
    spatial_artifact=spatial_artifact,
)

ports_fast = system.fast_ports(scene, frequency_hz)
loss_fast = system.fast_spatial(scene, frequency_hz)

ports_ref = system.reference_ports(scene, frequency_hz)
loss_ref = system.reference_spatial(scene, frequency_hz)

certified = system.certified_ports(scene, frequency_hz)

REFERENCE dispatches conductor-only scenes to the mixed finite-cross-section backend and heterogeneous/tensor-electric scenes to the coupled electric / magnetic interface backend. Homogeneous lossy-background power is represented by an unbounded exterior-domain integral rather than a finite world box.

FAST artifacts fail closed when geometry or material values fall outside the training domain. Tensor-electric scenes additionally require artifacts marked supports_tensor_electric; scalar material features are never used as an anisotropy proxy.

Isotropic hybrid FAST training

The existing hybrid dataset/training path remains available for isotropic package/background material domains:

python examples/vnext_generate_hybrid_dataset.py data/hybrid --count 128

python examples/vnext_train_hybrid_residual.py \
  data/hybrid \
  artifacts/hybrid-port.pt \
  --epochs 200

python examples/vnext_train_hybrid_spatial.py \
  data/hybrid \
  artifacts/hybrid-port.pt \
  artifacts/hybrid-spatial.pt \
  --epochs 120

The port decoder is reciprocal/passive by construction and returns PSD conductor plus aggregate electric-environment dissipation channels whose sum closes to the dissipative part of the predicted impedance. The spatial model then resolves those channels into continuous conductor, package, and optional unbounded-background loss fields.

Tensor-electric FAST port and spatial training

Tensor-electric training uses tensor-invariant material features for both the port model and the spatial latent state. The spatial decoder reuses the mature PSD conductor/package/background shape networks but is normalized against the tensor-aware port channels; it therefore does not collapse anisotropic permittivity/conductivity to scalar surrogates.

The current tensor FAST family is deliberately the hybrid package-aware family: its teacher/trainer requires at least one package region. A tensor homogeneous background may be sampled and learned together with those package regions. Background-only tensor scenes are supported by REFERENCE/CERTIFIED, but are not silently accepted by a tensor hybrid FAST artifact trained on a package domain.

A minimal in-memory research workflow is:

import numpy as np

from sdfmpneo_vnext import HybridSceneSamplerConfig, MQSConfig
from sdfmpneo_vnext.tensor_sampling import (
    TensorHybridSceneSamplerConfig,
    sample_tensor_hybrid_scene,
)
from sdfmpneo_vnext.tensor_training_data import TensorHybridTeacherSample
from sdfmpneo_vnext.tensor_spatial_training_data import (
    TensorHybridSpatialTeacherSample,
)
from sdfmpneo_vnext.tensor_neural import (
    train_tensor_hybrid_residual_surrogate,
)
from sdfmpneo_vnext.tensor_spatial_neural import (
    train_tensor_hybrid_spatial_loss_surrogate,
)

sampler = TensorHybridSceneSamplerConfig(
    base=HybridSceneSamplerConfig(),
    tensor_package_probability=1.0,
    tensor_background_probability=0.5,
)

teacher_config = MQSConfig()
rng = np.random.default_rng(7)
spatial_samples = []
for _ in range(16):
    scene, frequency_hz = sample_tensor_hybrid_scene(rng, sampler)
    port_truth = TensorHybridTeacherSample.generate(
        scene,
        frequency_hz,
        teacher_config=teacher_config,
    )
    spatial_samples.append(
        TensorHybridSpatialTeacherSample.generate(
            port_truth,
            teacher_config=teacher_config,
        )
    )

port, port_report = train_tensor_hybrid_residual_surrogate(
    tuple(sample.port for sample in spatial_samples),
    epochs=200,
)
spatial, spatial_report = train_tensor_hybrid_spatial_loss_surrogate(
    port,
    spatial_samples,
    epochs=120,
)

TensorHybridSpatialLossArtifact.prepare(...) produces the same prepared continuous-field interface used by the isotropic hybrid path, including:

• conductor-local local_dissipation_matrix/matrices queries;
• package-local/world package_*dissipation* queries;
• unbounded-background dissipation queries when the background is lossy;
• exact normalization to the tensor FAST port dissipation channels;
• compatibility with MeshfreeVNextSystem.fast_spatial and continuous thermal evolution.

Tensor artifact persistence

Tensor port and spatial artifacts can be published as one self-contained bundle:

from sdfmpneo_vnext.tensor_bundle import (
    publish_tensor_bundle,
    load_tensor_bundle,
)

publish_tensor_bundle(
    "artifacts/tensor-fast",
    port,
    spatial_artifact=spatial,
    overwrite=True,
)

loaded = load_tensor_bundle("artifacts/tensor-fast")
system = loaded.system
ports = system.fast_ports(scene, frequency_hz)
field = system.fast_spatial(scene, frequency_hz)

The manifest contains checksums, runtime capability metadata, and a semantic fingerprint binding the spatial artifact to the exact tensor port weights and normalization state.

Tensor bundle JSON inference

sdfmpneo-vnext-tensor artifacts/tensor-fast request.json --device auto

--device auto prefers CUDA, then MPS, then CPU. Tensor bundle loading preserves the dtype stored in the port/spatial artifacts.

Continuous thermal fields

A FAST spatial field can be coupled directly to continuous thermal evolution:

thermal = system.fast_continuous_thermal_field(
    scene,
    frequency_hz,
    HomogeneousThermalMedium(...),
)
temperature = thermal.temperature_step(position, time_s, currents)

The thermal field remains continuous in space and time. Package thermal interfaces and anisotropic background/package thermal tensors remain distinct from the electromagnetic tensor-electric model.

Scope boundaries

The vNext MVP intentionally fails closed outside its declared physics domain. In particular:

• tensor electric support is piecewise homogeneous, not a continuously varying tensor VIE;
• magnetic permeability is isotropic in the tensor-electric stage;
• partially intersecting packages are rejected; packages must be nested or disjoint;
• conductor branching/junction networks are not part of the spiral-coil MVP;
• tensor FAST training is AC-only; exact tensor DC uses REFERENCE/CERTIFIED;
• object-local quadrature/interface discretization is still a numerical approximation even though no global world mesh is required;
• phase change and nonlinear radiation are not part of the current thermal MVP.

Performance notes

See docs/VNEXT_PERFORMANCE.md for CUDA batching, CPU multiprocessing, precision policy and cached batch inference details.