scpn_fusion.hpc – HPC Bridge

The HPC subpackage provides the C++/Rust FFI bridge for interfacing with external high-performance solver kernels.

HPC Bridge

class scpn_fusion.hpc.hpc_bridge.HPCBridge(lib_path=None)[source]

Bases: object

Interface between Python and the compiled C++ Grad-Shafranov solver.

Loads the shared library (libscpn_solver.so / scpn_solver.dll) at construction time. If the library is not found the bridge gracefully degrades — is_available() returns False and the caller falls back to Python.

Parameters:

lib_path (str, optional) – Explicit path to the shared library. When None (default) the bridge searches trusted package-local locations only, unless SCPN_SOLVER_LIB is set explicitly.

is_available()[source]

Return True if the compiled solver library was loaded.

Return type:

bool

close()[source]

Release the C++ solver instance, if one was created.

Return type:

None

initialize(nr, nz, r_range, z_range, boundary_value=0.0)[source]

Create the C++ solver instance for the given grid dimensions.

Return type:

None

Parameters:
set_boundary_dirichlet(boundary_value=0.0)[source]

Set a fixed Dirichlet boundary value for psi edges, if supported.

Return type:

None

Parameters:

boundary_value (float)

solve(j_phi, iterations=100)[source]

Run the C++ solver for iterations sweeps.

Returns None if the library is not loaded (caller should fall back to a Python solver).

Return type:

Optional[ndarray[Any, dtype[float64]]]

Parameters:
solve_into(j_phi, psi_out, iterations=100)[source]

Run the C++ solver and write results into psi_out in-place.

Return type:

Optional[ndarray[Any, dtype[float64]]]

Parameters:
solve_neural(config_path=None)[source]

Run the O(1) Neural Equilibrium Surrogate. Requires NeuralEquilibriumKernel (JAX/NPZ weights).

Return type:

Optional[ndarray[Any, dtype[float64]]]

Parameters:

config_path (str | Path | None)

solve_until_converged(j_phi, max_iterations=1000, tolerance=1e-06, omega=1.8)[source]

Run solver until convergence, if native API is available.

Returns (psi, iterations_used, final_delta). If the library is unavailable or uninitialized, returns None.

Return type:

Optional[tuple[ndarray[Any, dtype[float64]], int, float]]

Parameters:
solve_until_converged_into(j_phi, psi_out, max_iterations=1000, tolerance=1e-06, omega=1.8)[source]

Run convergence API and write results into psi_out in-place.

Return type:

Optional[tuple[int, float]]

Parameters:
scpn_fusion.hpc.hpc_bridge.compile_cpp()[source]

Compile the C++ solver from source.

Looks for solver.cpp in the same directory as this module and invokes g++ to produce a shared library.

Returns:

Path to the compiled library, or None on failure.

Return type:

str or None