Dynamic solver factory

Zmag_bins.Zmag_dynamic_stereo_solvers is the recommended entry point for time-dependent stereographic LLG. It selects the implementation and exposes a uniform API via attribute forwarding.

from Zmag_bins.Zmag_dynamic_stereo_solvers import create_stereo_solver

sim = create_stereo_solver(args_init_sim, model="demag")  # or "nodemag"
sim.set_mesh(...)
sim.init_dynamic(args_init_dyn)
sim.solve_problem()   # defined on Z_sim_dynamic_stereo_base

sim.impl is the underlying Z_sim_dynamic_stereo_demag or Z_sim_dynamic_stereo_nodemag instance.

Exports

• StereoDemagSolver, StereoNoDemagSolver — validation + delegation wrappers

• create_stereo_solver() — factory

• Z_sim_dynamic_stereo_demag, Z_sim_dynamic_stereo_nodemag — concrete classes

Shared timestep control, checkpoints, and the main loop are documented in Shared base module. Model-specific FEM spaces and SNES forms are in Demag dynamic solver and Nodemag dynamic solver.

Factory and thin wrappers for stereographic dynamic solvers.

• StereoDemagSolver — Z_sim_dynamic_stereo_demag

• StereoNoDemagSolver — Z_sim_dynamic_stereo_nodemag

create_stereo_solver() is the recommended entry point. Wrappers forward attribute access to StereoSolverBase.impl.

class Zmag_bins.Zmag_dynamic_stereo_solvers.StereoSolverBase(args_init_sim: dict[str, Any])

Bases: ABC

Abstract facade over dynamic stereographic solver implementations.

Deep-copies args_init_sim and forwards attributes to impl.

__init__(args_init_sim: dict[str, Any])

Deep-copy initialization dict and construct the concrete solver.

Parameters:

args_init_sim (dict) – Simulation setup dictionary for the underlying class.

property impl

Underlying Z_sim_dynamic_stereo_* instance.

class Zmag_bins.Zmag_dynamic_stereo_solvers.StereoDemagSolver(args_init_sim: dict[str, Any])

Bases: StereoSolverBase

Wrapper for Z_sim_dynamic_stereo_demag.

Requires demag in energy_terms.

class Zmag_bins.Zmag_dynamic_stereo_solvers.StereoNoDemagSolver(args_init_sim: dict[str, Any])

Bases: StereoSolverBase

Wrapper for Z_sim_dynamic_stereo_nodemag.

Strips demag from energy_terms if present.

Zmag_bins.Zmag_dynamic_stereo_solvers.create_stereo_solver(args_init_sim: dict[str, Any], model: str = 'demag') → StereoSolverBase

Build a stereographic dynamic solver wrapper.

Parameters:

• args_init_sim (dict) – Simulation setup dictionary.

• model (str) – "demag" or "nodemag".

Returns:

• StereoSolverBase

• Delegating wrapper around the concrete solver.

Raises:

ValueError – If model is unrecognized.

class Zmag_bins.Zmag_dynamic_stereo_solvers.Z_sim_dynamic_stereo_demag(args_init_sim: dict)

Bases: Z_sim_dynamic_stereo_base

Stereographic LLG with mixed unknowns (q_A, q_B, phi) and magnetostatics.

Inherits the adaptive time loop from Z_sim_dynamic_stereo_base and adds Fredkin–Koehler magnetostatics plus optional C++ BEM acceleration.

class NonlinearSNESProblem_qAqB(sim, F_expr)

Bases: object

SNES nonlinear problem wrapper for qA/qB/phi system.

F(snes, x, F)

J(snes, x, J, P)

__init__(args_init_sim: dict) → None

Initialize demag solver configuration and stereographic chart basis.

Parameters:

args_init_sim (dict) – Requires alpha, energy_terms (including demag), NeumannBC, printout, path_dirs. Optional: projection_pole, sigma2_floor.

Raises:

ValueError – If demag is missing from energy_terms.

close_output(target: str)

Close VTX/XDMF writers opened by open_output() for target.

compute_energy()

Evaluate the atlas-weighted micromagnetic energy.

Returns:

• numpy.ndarray

• [exchange, uniaxial, cubic, demag, zeeman, total] (inactive terms are zero).

init_dynamic(args_init_dyn: dict)

Configure time integration, SNES, BDF history, ramps, and I/O.

Call after mesh setup, materials, chart initialization, magnetostatics, and BEM assembly.

Parameters:

args_init_dyn (dict) – Requires t_start, dt, step_start, step_end, first_run, checkpoint_every, write_target, and cfl_settings. See Configuration reference in the manual.

Raises:

• ValueError – On invalid configuration keys or values.

• FileNotFoundError – If required path_dirs entries are missing.

• KeyError – If a required path_dirs key is absent.

open_output(target: str, filename: str)

Open BP (VTX) and optional XDMF writers for a named output field.

Parameters:

• target (str) – One of mag, qA, qB, phi, demag, heff, atlas masks/weights, etc. (see FEATURE_MATRIX.md).

• filename (str) – Base path for .bp output files.

read_checkpoint_demag(filename)

Restore magnetostatic potential and demagnetizing field from checkpoint.

Parameters:

filename (str)

Returns:

(phi, h_demag) with h_demag = -grad(phi).

Return type:

tuple[dolfinx.fem.Function, dolfinx.fem.Function]

read_checkpoint_mesh(mpi_comm, filename)

Restore distributed mesh and meshtags from an ADIOS BP file.

Returns:

(domain, boundary_facets, cell_tags, facet_tags).

Return type:

tuple

read_checkpoint_time(run_dir, filename)

Parse energies log and locate latest checkpoint_timestep_*.bp.

Returns:

(step_start, t_start, dt).

Return type:

tuple[int, float, float]

set_BEMcpp(BEM_dir: str, cpp_backend: str | None = None)

Assemble the BEM operator for the Laplace subproblem.

Parameters:

• BEM_dir (str) – BEM data directory for bem_assembler.bem_assembler.BEMAssembler.

• cpp_backend (str, optional) – Optional backend preset.

set_magnetostatics(interfaces: list[dict], surface_tag: int)

Wire the magnetostatic helper and interface facet measures.

Parameters:

• interfaces (list[dict]) – Interface definitions with tag keys.

• surface_tag (int) – Exterior boundary tag for Dirichlet data on \(\varphi\).

solve_magnetostatics(step)

Restart hook: optionally warm-start demag from checkpoint, then reconcile.

Parameters:

step (int) – Current step; triggers reload when step == step_start on restart.

Notes

Checkpoint phi matches the writer’s BEM/partition. After remesh the live BEM differs, so any loaded phi is only a warm start and is immediately re-equilibrated via _refresh_demag_state_from_current_q(). When init_dynamic already reconciled after atlas restore, this hook skips the redundant load.

solve_weak_form(max_outer_override=None)

Advance one timestep: BDF shift, atlas update, outer split, and SNES on (q_A,q_B,phi).

Called from solve_problem() inside each retry attempt. Residual/thermo/closure gates run in the base class after this returns.

Parameters:

max_outer_override (int, optional) – Cap operator-split iterations.

Returns:

Defects and convergence metadata (iters, q_defect, phi_defect, …).

Return type:

dict

write_checkpoint(filename)

Write ADIOS checkpoint plus npz chart histories.

Parameters:

filename (str) – Path ending in .bp; npz companions use the same stem.

write_output(target: str)

Update and write the field bundle for target at time self.t.

Populates derived fields (mag, demag, atlas masks, etc.) then writes to BP/XDMF writers registered for target.

write_phi1_boundary(filename)

Export boundary potential phi1 (Neumann data + BEM) to a BP checkpoint.

Parameters:

filename (str)

write_xdmf_checkpoint(target: str, filename: str)

Export a single-time XDMF snapshot.

Parameters:

• target (str) – mag, phi, demag, heff, chart_ind, q_norm, qA, qB, etc.

• filename (str) – Output .xdmf path.

class Zmag_bins.Zmag_dynamic_stereo_solvers.Z_sim_dynamic_stereo_nodemag(args_init_sim: dict)

Bases: Z_sim_dynamic_stereo_base

Stereographic LLG with mixed unknowns (q_A, q_B) only.

Shares the base-class time loop and atlas with the demag variant but omits V_phi and magnetostatics.

class NonlinearSNESProblem_qAqB(sim, F_expr)

Bases: object

SNES nonlinear problem wrapper for the mixed qA/qB system.

F(snes, x, F)

J(snes, x, J, P)

__init__(args_init_sim: dict) → None

Initialize no-demag solver configuration and chart basis.

Parameters:

args_init_sim (dict) – See class docstring. Raises ValueError if no energy terms remain after removing demag.

close_output(target: str)

Close qAqB-local output writers.

compute_energy()

Evaluate atlas-weighted energy without a demag term.

Returns:

• numpy.ndarray

• Energy components followed by total.

init_dynamic(args_init_dyn: dict)

Configure time integration, SNES, BDF history, ramps, and I/O for (q_A, q_B).

Same contract as the demag solver except magnetostatics, demag continuation, and demag-only outputs are absent.

Parameters:

args_init_dyn (dict) – Dynamic configuration dictionary (requires cfl_settings). See Configuration reference in the manual.

Raises:

• ValueError – On invalid configuration keys or values.

• FileNotFoundError – If required path_dirs entries are missing.

• KeyError – If a required path_dirs key is absent.

open_output(target: str, filename: str)

Open BP (VTX) and optional XDMF time-series writers for a field target.

Parameters:

• target (str) – Field name (see FEATURE_MATRIX.md). Demag-only targets raise in nodemag.

• filename (str) – Base path for .bp output (XDMF uses parallel .xdmf naming).

read_checkpoint_demag(filename)

Not supported in nodemag.

Raises:

• ValueError –

• Always raised. –

read_checkpoint_mesh(mpi_comm, filename)

Read checkpointed mesh and tags from BP.

read_checkpoint_time(run_dir, filename)

Read restart step/time/dt from checkpoint energies table.

set_BEMcpp(BEM_dir: str)

Ignored in nodemag; no BEM demagnetizing operator is assembled.

set_magnetostatics(interfaces: list[dict], surface_tag: int)

Ignored in nodemag; present so shared drivers can call the demag API safely.

solve_magnetostatics(step)

Write restart magnetization checkpoint when resuming from a saved state.

solve_weak_form(max_outer_override=None)

Advance one timestep on (q_A,q_B) with q-only outer fixed-point and SNES.

Called from solve_problem() inside each retry attempt. Acceptance gates (residual, thermo, closure) run in the base class after this returns.

Parameters:

max_outer_override (int, optional) – Cap outer-split iterations.

Returns:

q_defect, converged, outer-iteration metadata.

Return type:

dict

write_checkpoint(filename)

Checkpoint mesh, tags, and qA/qB BDF history npz files.

write_output(target: str)

Update and write fields for target at current time self.t.

Parameters:

target (str)

write_phi1_boundary(filename)

Not supported in nodemag; raises ValueError.

write_xdmf_checkpoint(target: str, filename: str)

Checkpoint field in XDMF for no-demag qA/qB model.