vmecpp package

class vmecpp.JxBOut(**data)

Bases: BaseModelWithNumpy

Parameters:

data (Any)

amaxfor: jt.Float[np.ndarray, 'n_surfaces']

100 * Maximum value of the real space force residual on each radial surface.

aminfor: jt.Float[np.ndarray, 'n_surfaces']

100 * Minimum value of the real space force residual on each radial surface.

avforce: jt.Float[np.ndarray, 'n_surfaces']

Average force residual on each radial surface.

bdotb: jt.Float[np.ndarray, 'n_surfaces']

<B * B> on full-grid.

bdotgradv: jt.Float[np.ndarray, 'n_surfaces']
bdotk: jt.Float[np.ndarray, 'num_full nZnT']
bsubs3: jt.Float[np.ndarray, 'num_full nZnT']
bsubu3: jt.Float[np.ndarray, 'num_half nZnT']
bsubv3: jt.Float[np.ndarray, 'num_half nZnT']
bsupu3: jt.Float[np.ndarray, 'num_full nZnT']
bsupv3: jt.Float[np.ndarray, 'num_full nZnT']
itheta: jt.Float[np.ndarray, 'num_half nZnT']

Poloidal surface current.

itheta = (d B_s/dPhi - d B_phi/ds)/mu0

izeta: jt.Float[np.ndarray, 'num_half nZnT']

Toroidal surface current.

izeta = (-d B_s/dTheta + d B_theta/ds)/mu0

jcrossb: jt.Float[np.ndarray, 'num_full nZnT']

Magnitude of j x B at each grid point.

jdotb: jt.Float[np.ndarray, 'n_surfaces']

<j * B> on full-grid.

jdotb_sqrtg: jt.Float[np.ndarray, 'num_full nZnT']

Product of j * B and sqrt(g) at each grid point.

jpar2: jt.Float[np.ndarray, 'n_surfaces']

Flux-surface-averaged squared parallel current density <j||^2>.

jperp2: jt.Float[np.ndarray, 'n_surfaces']

Flux-surface-averaged squared perpendicular current density <j-perp^2>.

jsups3: jt.Float[np.ndarray, 'num_half nZnT']

Contravariant current density component j^s on the half grid.

j^s = (d B_theta/dPhi - d B_pih/dTheta)/(mu0 * V’)

jsupu3: jt.Float[np.ndarray, 'num_full nZnT']

Contravariant current density component j^u on the full grid.

j^u = itheta/V’

jsupv3: jt.Float[np.ndarray, 'num_full nZnT']

Contravariant current density component j^v on the full grid.

j^u = izeta/V’

jxb_gradp: jt.Float[np.ndarray, 'num_full nZnT']

Dot product of j x B and grad(p) at each grid point.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'ser_json_inf_nan': 'strings'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

phin: jt.Float[np.ndarray, 'n_surfaces']

Normalized, enclosed toroidal flux at each radial surface.

phin = toroidal_flux/toroidal_flux[-1]

pprim: jt.Float[np.ndarray, 'n_surfaces']

Radial derivative of the pressure profile.

sqrtg3: jt.Float[np.ndarray, 'num_full nZnT']

Jacobian determinant sqrt(g) at each grid point.

class vmecpp.MagneticFieldResponseTable(**data)

Bases: BaseModelWithNumpy

Pydantic model mirroring the C++ makegrid::MagneticFieldResponseTable struct.

Holds the precomputed magnetic field response on a grid, separated by coil circuit. Each field component (b_r, b_p, b_z) is a list where each element corresponds to a circuit and contains the flattened 1D array of field values on the grid for that circuit carrying unit current.

Parameters:

data (Any)

b_p: jt.Float[np.ndarray, 'num_coils num_mgrid_cells']

Cylindrical Phi components of magnetic field per circuit.

b_r: jt.Float[np.ndarray, 'num_coils num_mgrid_cells']

Cylindrical R components of magnetic field per circuit.

b_z: jt.Float[np.ndarray, 'num_coils num_mgrid_cells']

Cylindrical Z components of magnetic field per circuit.

static from_coils_file(coils_path, makegrid_parameters)
Parameters:
Return type:

MagneticFieldResponseTable

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'ser_json_inf_nan': 'strings'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: MakegridParameters
class vmecpp.MakegridParameters(**data)

Bases: BaseModelWithNumpy

Pydantic model mirroring the C++ makegrid::MakegridParameters struct.

Parameters defining the grid for external magnetic field calculations (mgrid file).

Parameters:

data (Any)

assume_stellarator_symmetry: bool

If true, compute on half-period and mirror.

static from_file(input_file)
Parameters:

input_file (str | Path)

Return type:

MakegridParameters

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'ser_json_inf_nan': 'strings'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

normalize_by_currents: bool

If true, normalize the magnetic field by coil currents and windings.

number_of_field_periods: int

Number of toroidal field periods.

number_of_phi_grid_points: int

Number of toroidal grid points per field period.

number_of_r_grid_points: int

Number of radial grid points.

number_of_z_grid_points: int

Number of vertical grid points.

r_grid_maximum: float

Radial coordinate of the last grid point.

r_grid_minimum: float

Radial coordinate of the first grid point.

z_grid_maximum: float

Vertical coordinate of the last grid point.

z_grid_minimum: float

Vertical coordinate of the first grid point.

class vmecpp.Mercier(**data)

Bases: BaseModelWithNumpy

Parameters:

data (Any)

DMerc: jt.Float[np.ndarray, 'n_surfaces']

Full Mercier stability criterion.

Dcurr: jt.Float[np.ndarray, 'n_surfaces']

Mercier criterion contribution due to plasma currents.

Dgeod: jt.Float[np.ndarray, 'n_surfaces']

Mercier criterion contribution due to geodesic curvature.

Dshear: jt.Float[np.ndarray, 'n_surfaces']

Mercier criterion contribution due to magnetic shear.

Dwell: jt.Float[np.ndarray, 'n_surfaces']

Mercier criterion contribution due to magnetic well.

d_pressure_d_s: jt.Float[np.ndarray, 'n_surfaces']

Radial derivative of pressure profile.

d_toroidal_current_d_s: jt.Float[np.ndarray, 'n_surfaces']

Radial derivative of enclosed toroidal current.

d_volume_d_s: jt.Float[np.ndarray, 'n_surfaces']

Radial derivative of plasma volume with respect to s.

iota: jt.Float[np.ndarray, 'n_surfaces']

Rotational transform iota.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'ser_json_inf_nan': 'strings'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pressure: jt.Float[np.ndarray, 'n_surfaces']

Pressure profile p.

s: jt.Float[np.ndarray, 'n_surfaces']

Normalized toroidal flux coordinate s.

shear: jt.Float[np.ndarray, 'n_surfaces']

Magnetic shear profile.

toroidal_current: jt.Float[np.ndarray, 'n_surfaces']

Enclosed toroidal current profile.

toroidal_flux: jt.Float[np.ndarray, 'n_surfaces']

Enclosed toroidal magnetic flux phi.

well: jt.Float[np.ndarray, 'n_surfaces']

Magnetic well profile.

class vmecpp.Threed1Volumetrics(**data)

Bases: BaseModelWithNumpy

Parameters:

data (Any)

avg_bpol: float

Volume-averaged poloidal magnetic field energy.

avg_btor: float

Volume-averaged toroidal magnetic field energy.

avg_ekin: float

Volume-averaged kinetic energy.

avg_modb: float

Volume-averaged |B|.

avg_p: float

Volume-averaged plasma pressure.

int_bpol: float

Total poloidal magnetic field energy B_phi^2/(2 mu0) integrated over the plasma volume.

int_btor: float

Total toroidal magnetic field energy integrated over the plasma volume.

int_ekin: float

Total kinetic energy integrated over the plasma volume.

int_modb: float

Total |B| integrated over the plasma volume.

int_p: float

Total plasma pressure integrated over the plasma volume.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'ser_json_inf_nan': 'strings'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vmecpp.VmecInput(**data)

Bases: BaseModelWithNumpy

The input to a VMEC++ run. Contains settings as well as the definition of the plasma boundary.

Python equivalent of a VMEC++ JSON input file or a classic INDATA file (e.g. “input.best”).

Deserialize from JSON and serialize to JSON using the usual pydantic methods: model_validate_json and model_dump_json.

Parameters:

data (Any)

ac: jt.Float[np.ndarray, 'ac_len']

Enclosed toroidal current profile coefficients.

ac_aux_f: jt.Float[np.ndarray, 'ac_aux_len']

values at knots

Type:

Spline toroidal current profile

ac_aux_s: jt.Float[np.ndarray, 'ac_aux_len']

knot locations in s

Type:

Spline toroidal current profile

ai: jt.Float[np.ndarray, 'ai_len']

Iota profile coefficients.

ai_aux_f: jt.Float[np.ndarray, 'ai_aux_len']

values at knots

Type:

Spline iota profile

ai_aux_s: jt.Float[np.ndarray, 'ai_aux_len']

knot locations in s

Type:

Spline iota profile

am: jt.Float[np.ndarray, 'am_len']

Mass/pressure profile coefficients.

Units: Pascals for pressure.

am_aux_f: jt.Float[np.ndarray, 'am_aux_len']

values at knots

Type:

Spline mass/pressure profile

am_aux_s: jt.Float[np.ndarray, 'am_aux_len']

knot locations in s

Type:

Spline mass/pressure profile

aphi: jt.Float[np.ndarray, 'aphi_len']

Radial flux zoning profile coefficients.

bloat: float

Bloating factor (for constrained toroidal current)

curtor: float

Net toroidal current in A.

The toroidal current profile is scaled to yield this total.

static default()

Construct a VmecInput with the same default settings as VMEC2000.

delt: float

Initial value for artificial time step in iterative solver.

extcur: jt.Float[np.ndarray, 'ext_current']

Coil currents in A.

static from_file(input_file)

Build a VmecInput from either a VMEC++ JSON input file or a classic INDATA file.

Parameters:

input_file (str | Path)

Return type:

VmecInput

ftol_array: jt.Float[np.ndarray, 'num_grids']

Requested force tolerance for convergence per multigrid step.

gamma: float

Adiabatic index (ratio of specific heats).

Specifying 0 implies that the pressure profile is specified. For all other values, the mass profile is specified.

lasym: bool

Flag to indicate non-stellarator-symmetry.

  • False, assumes stellarator symmetry (only cosine/sine coefficients used).

  • True, (currently unsupported) allows for non-stellarator-symmetric terms.

lforbal: bool

directly compute innermost flux surface geometry from radial force balance

Type:

Hack

lfreeb: bool

Flag to indicate free-boundary.

If True, run in free-boundary mode; if False, fixed-boundary.

mgrid_file: typing.Annotated[str, pydantic.Field(max_length=200)]

Full path for vacuum Green’s function data.

NetCDF MGRID file with magnetic field response factors for external coils.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'ser_json_inf_nan': 'strings'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mpol: int

Number of poloidal Fourier harmonics; m = 0, 1, …, (mpol-1)

ncurr: typing.Literal[0, 1]

Select constraint on iota or enclosed toroidal current profiles.

  • 0: constrained-iota (rotational transform profile specified)

  • 1: constrained-current (toroidal current profile specified)

nfp: int

Number of toroidal field periods (=1 for Tokamak)

niter_array: jt.Int[np.ndarray, 'num_grids']

Maximum number of iterations per multigrid step.

ns_array: jt.Int[np.ndarray, 'num_grids']

Number of flux surfaces per multigrid step.

Each entry >= 3 and >= previous entry.

nstep: int

Printout interval at which convergence progress is logged.

ntheta: int

Number of poloidal grid points (ntheta >= 0).

Controls the poloidal resolution in real space. If 0, chosen automatically as minimally allowed. Must be at least 2*mpol + 6.

ntor: int

Number of toroidal Fourier harmonics; n = -ntor, -ntor+1, …, -1, 0, 1, …, ntor-1, ntor.

nvacskip: int

Number of iterations between full vacuum calculations.

nzeta: int

Number of toroidal grid points (nzeta >= 0).

Controls the toroidal resolution in real space. If 0, chosen automatically as minimally allowed. Must be at least 2*ntor + 4. We typically use use phi as the convention for the toroidal angle, the name nzeta is due to beckwards compatibility.

pcurr_type: ProfileType

Parametrization of toroidal current profile.

phiedge: float

Total enclosed toroidal magnetic flux in Vs == Wb.

  • In fixed-boundary, this determines the magnetic field strength.

  • In free-boundary, the magnetic field strength is given externally,

so this determines cross-section area and volume of the plasma.

piota_type: ProfileType

Parametrization of iota (rotational transform) profile.

pmass_type: ProfileType

Parametrization of mass/pressure profile.

pres_scale: float

Global scaling factor for mass/pressure profile.

raxis_c: jt.Float[np.ndarray, 'ntor_plus_1']

Magnetic axis coefficients for R ~ cos(n*v); stellarator-symmetric.

At least 1 value required, up to n=ntor considered.

raxis_s: jt.Float[np.ndarray, 'ntor_plus_1'] | None

Magnetic axis coefficients for R ~ sin(n*v); non-stellarator-symmetric.

Up to n=ntor considered; first entry (n=0) is ignored. Only used if lasym=True.

rbc: SerializableSparseCoefficientArray[jt.Float[np.ndarray, 'mpol two_ntor_plus_one']]

Boundary coefficients for R ~ cos(m*u - n*v); stellarator-symmetric

rbs: SerializableSparseCoefficientArray[jt.Float[np.ndarray, 'mpol two_ntor_plus_one']] | None

Boundary coefficients for R ~ sin(m*u - n*v); non-stellarator-symmetric.

Only used if lasym=True.

static resize_2d_coeff(coeff, mpol_new, ntor_new)

Resizes a 2D NumPy array representing Fourier coefficients, padding with zeros or truncating as needed.

Parameters:

  • coeff (Float[ndarray, 'mpol two_ntor_plus_one']) – A NumPy array of shape (mpol, 2 * ntor + 1).

  • mpol_new (int) – The new number of poloidal modes.

  • ntor_new (int) – The new number of toroidal modes.

Return type:

Float[ndarray, 'mpol_new two_ntor_new_plus_one']

Examples

>>> coeff = np.array([[1, 2, 3, 4, 5], [6, 7, 8, 9, 10]])
>>> VmecInput.resize_2d_coeff(coeff, 3, 3)
array([[ 0.,  1.,  2.,  3.,  4.,  5.,  0.],
       [ 0.,  6.,  7.,  8.,  9., 10.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.]])

>>> VmecInput.resize_2d_coeff(coeff, 1, 1)
array([[2., 3., 4.]])

>>> VmecInput.resize_2d_coeff(coeff, 4, 1)
array([[2., 3., 4.],
       [7., 8., 9.],
       [0., 0., 0.],
       [0., 0., 0.]])
return_outputs_even_if_not_converged: bool

If true, return the outputs even if VMEC++ did not converge.

Otherwise a RuntimeError will be raised.

save(output_path, **kwargs)
Parameters:

output_path (str | Path)

Return type:

None

spres_ped: float

Location of pressure pedestal in s.

Outside this radial location, pressure is constant.

tcon0: float

Constraint force scaling factor for ns –> 0.

to_json(**kwargs)

Serialize the object to JSON.

Keyword Arguments:

**kwargs – Additional keyword arguments to forward to the model_dump_json method.

Return type:

str

zaxis_c: jt.Float[np.ndarray, 'ntor_plus_1'] | None

Magnetic axis coefficients for Z ~ cos(n*v); non-stellarator-symmetric.

Only used if lasym=True.

zaxis_s: jt.Float[np.ndarray, 'ntor_plus_1']

Magnetic axis coefficients for Z ~ sin(n*v); stellarator-symmetric.

Up to n=ntor considered; first entry (n=0) is ignored.

zbc: SerializableSparseCoefficientArray[jt.Float[np.ndarray, 'mpol two_ntor_plus_one']] | None

Boundary coefficients for Z ~ cos(m*u - n*v); non-stellarator-symmetric.

Only used if lasym=True.

zbs: SerializableSparseCoefficientArray[jt.Float[np.ndarray, 'mpol two_ntor_plus_one']]

Boundary coefficients for Z ~ sin(m*u - n*v); stellarator-symmetric

class vmecpp.VmecOutput(**data)

Bases: BaseModelWithNumpy

Container for the full output of a VMEC run.

Parameters:

data (Any)

input: VmecInput

The input to the VMEC run that produced this output.

jxbout: JxBOut

Python equivalent of VMEC’s “jxbout” file.

mercier: Mercier

Python equivalent of VMEC’s “mercier” file.

Contains radial profiles and stability criteria relevant for Mercier stability analysis, including the Mercier criterion and its decomposition into shear, well, current, and geodesic contributions. Also includes profiles of rotational transform, toroidal flux, pressure, and their derivatives.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'ser_json_inf_nan': 'strings'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

threed1_volumetrics: Threed1Volumetrics

Python equivalent of VMEC’s volumetrics section in the “threed1” file.

Contains global and flux-surface-averaged quantities such as total and average pressure, poloidal and toroidal magnetic field energies, kinetic energy, and related integrals. Useful for postprocessing and global equilibrium characterization.

wout: VmecWOut

Python equivalent of VMEC’s “wout” file.

class vmecpp.VmecWOut(**data)

Bases: BaseModelWithNumpy

Python equivalent of a VMEC “wout file”.

VmecWOut exposes the layout that SIMSOPT expects. The save method produces a NetCDF file compatible with SIMSOPT/Fortran VMEC.

Parameters:

data (Any)

Aminor_p: float

Minor radius of the plasma.

DCurr: jt.Float[np.ndarray, 'n_surfaces']

Mercier stability criterion contribution due to plasma currents.

DGeod: jt.Float[np.ndarray, 'n_surfaces']

Mercier stability criterion contribution due to geodesic curvature.

DMerc: jt.Float[np.ndarray, 'n_surfaces']

Full Mercier stability criterion on the full-grid.

DShear: jt.Float[np.ndarray, 'n_surfaces']

Mercier stability criterion contribution due to magnetic shear.

DWell: jt.Float[np.ndarray, 'n_surfaces']

Mercier stability criterion contribution due to magnetic well.

IonLarmor: float

Larmor radius of plasma ions.

Rmajor_p: float

Major radius of the plasma.

ac: jt.Float[np.ndarray, 'preset']

Enclosed toroidal current profile coefficients (copied from input).

ac_aux_f: AuxFType[jt.Float[np.ndarray, 'ndfmax']]

values at knots (copied from input).

Type:

Spline toroidal current profile

ac_aux_s: AuxSType[jt.Float[np.ndarray, 'ndfmax']]

knot locations in s (copied from input).

Type:

Spline toroidal current profile

ai: jt.Float[np.ndarray, 'preset']

Iota profile coefficients (copied from input).

ai_aux_f: AuxFType[jt.Float[np.ndarray, 'ndfmax']]

values at knots (copied from input).

Type:

Spline iota profile

ai_aux_s: AuxSType[jt.Float[np.ndarray, 'ndfmax']]

knot locations in s (copied from input).

Type:

Spline iota profile

am: jt.Float[np.ndarray, 'preset']

Mass/pressure profile coefficients (copied from input).

am_aux_f: AuxFType[jt.Float[np.ndarray, 'ndfmax']]

values at knots (copied from input).

Type:

Spline mass/pressure profile

am_aux_s: AuxSType[jt.Float[np.ndarray, 'ndfmax']]

knot locations in s (copied from input).

Type:

Spline mass/pressure profile

aspect: float

Aspect ratio (major radius over minor radius) of the plasma boundary.

b0: float

Toroidal magnetic flux density from poloidal current and magnetic axis position at phi=0.

bdotb: jt.Float[np.ndarray, 'n_surfaces']

<B * B> on full-grid.

bdotgradv: jt.Float[np.ndarray, 'n_surfaces']

Flux-surface-averaged toroidal magnetic field component B * grad(v) on full- grid.

beta_vol: jt.Float[np.ndarray, 'n_surfaces']

Flux-surface averaged plasma beta on half-grid.

betapol: float

Poloidal plasma beta.

The ratio of the total thermal energy of the plasma, to the total poloidal magnetic energy. beta=W_th/W_{B_theta}=int p dV/(int B_theta^2/(2 mu_0) dV)

betator: float

Toroidal plasma beta.

The ratio of the total thermal energy of the plasma, to the total toroidal magnetic energy. beta=W_th/W_{B_phi}=int p dV/(int B_phi^2/(2 mu_0) dV)

betatotal: float

Total plasma beta.

The ratio of the total thermal energy of the plasma, to the total magnetic energy. beta=W_th/W_B=int p dV/(int B/(2 mu_0) dV)

betaxis: float

Plasma beta on the magnetic axis.

bmnc: jt.Float[np.ndarray, 'mn_mode_nyq n_surfaces']

Fourier coefficients of the magnetic field strength |B| on the half-grid.

bsubsmns: jt.Float[np.ndarray, 'mn_mode_nyq n_surfaces']

Fourier coefficients of the covariant magnetic field component B_s on the full- grid.

bsubumnc: jt.Float[np.ndarray, 'mn_mode_nyq n_surfaces']

Fourier coefficients of the covariant magnetic field component B_theta on the half-grid.

bsubvmnc: jt.Float[np.ndarray, 'mn_mode_nyq n_surfaces']

Fourier coefficients of the covariant magnetic field component B_phi on the half-grid.

bsupumnc: jt.Float[np.ndarray, 'mn_mode_nyq n_surfaces']

Fourier coefficients of the contravariant magnetic field component B^theta on the half-grid.

bsupvmnc: jt.Float[np.ndarray, 'mn_mode_nyq n_surfaces']

Fourier coefficients of the contravariant magnetic field component B^phi on the half-grid.

buco: jt.Float[np.ndarray, 'n_surfaces']

Profile of enclosed toroidal current I on half-grid.

bvco: jt.Float[np.ndarray, 'n_surfaces']

Profile of enclosed poloidal ribbon current G on half-grid.

chi: jt.Float[np.ndarray, 'n_surfaces']

Enclosed poloidal magnetic flux chi on the full-grid.

chipf: jt.Float[np.ndarray, 'n_surfaces']

Radial derivative of enclosed poloidal magnetic flux chi’ on the full-grid.

ctor: float

Net toroidal plasma current.

equif: jt.Float[np.ndarray, 'n_surfaces']

Radial force balance residual on full-grid.

extcur: typing.Annotated[jt.Float[np.ndarray, 'ext_current'], pydantic.BeforeValidator(lambda x: x if np.shape(x) != () else np.array([])), pydantic.PlainSerializer(lambda x: x if np.shape(x) != (0,) else netCDF4.default_fillvals['f8'])]

Coil currents in A.

for free-boundary runs, extcur has shape (nextcur,) for fixed-boundary it is a scalar float extcur=nan

static from_wout_file(wout_filename)

Load wout contents in NetCDF format.

This is the format used by Fortran VMEC implementations and the one expected by SIMSOPT. We allow for additional attributes to be present in the file, for compatibility with wouf files from other VMEC versions, but require at least the fields produced by VMEC++.

Parameters:

wout_filename (str | Path)

Return type:

VmecWOut

fsql: float

Invariant force residual of the force on lambda at end of the run.

fsqr: float

Invariant force residual of the force on R at end of the run.

fsqt: jt.Float[np.ndarray, 'time']

Evolution of the total force residual along the run.

fsqz: float

Invariant force residual of the force on Z at end of the run.

ftolv: float

Force tolerance value used to determine convergence.

gamma: float

Adiabatic index gamma (copied from input).

gmnc: jt.Float[np.ndarray, 'mn_mode_nyq n_surfaces']

Fourier coefficients of the Jacobian sqrt(g) on the half-grid.

ier_flag: int

Status code indicating success or problems during the VMEC++ run.

input_extension: typing.Annotated[str, pydantic.Field(max_length=100)]

File extension of the input file.

iotaf: jt.Float[np.ndarray, 'n_surfaces']

Rotational transform iota on the full-grid.

iotas: jt.Float[np.ndarray, 'n_surfaces']

Rotational transform iota on the half-grid.

itfsq: int

Number of force-balance iterations after which the run terminated.

jcuru: jt.Float[np.ndarray, 'n_surfaces']

Radial derivative of enclosed poloidal current on full-grid.

jcurv: jt.Float[np.ndarray, 'n_surfaces']

Radial derivative of enclosed toroidal current on full-grid.

jdotb: jt.Float[np.ndarray, 'n_surfaces']

<j * B> on full-grid.

lasym: typing.Annotated[bool, pydantic.PlainSerializer(lambda x: int(x)), pydantic.BeforeValidator(lambda x: bool(x)), pydantic.Field(alias='lasym__logical__')]

Flag indicating non-stellarator-symmetry.

property lasym__logical__

This is how the attribute is called in the Fortran wout file.

lfreeb: typing.Annotated[bool, pydantic.PlainSerializer(lambda x: int(x)), pydantic.BeforeValidator(lambda x: bool(x)), pydantic.Field(alias='lfreeb__logical__')]

Flag indicating free-boundary computation.

property lfreeb__logical__

This is how the attribute is called in the Fortran wout file.

lmns: jt.Float[np.ndarray, 'mn_mode n_surfaces']

Fourier coefficients for lambda stream function on the half-grid.

lmns_full: jt.Float[np.ndarray, 'mn_mode n_surfaces']

Fourier coefficients for lambda stream function on the full-grid.

This quantity is VMEC++ specific and required for hot-restart to work properly. We store it with the Fortran convention for the order of the dimensions for consistency with lmns.

mass: jt.Float[np.ndarray, 'n_surfaces']

Plasma mass profile m on half-grid.

mgrid_file: typing.Annotated[str, pydantic.Field(max_length=200)]

Full path for vacuum Green’s function data (copied from input).

mgrid_mode: MgridModeType

Indicates if the mgrid file was normalized to unit currents (“S”) or not (“R”).

mnmax: int

Number of Fourier coefficients for the state vector.

mnmax_nyq: int

Number of Fourier coefficients for the Nyquist-quantities.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'ser_json_inf_nan': 'strings', 'serialize_by_alias': False, 'validate_by_alias': False, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mpol: int

Number of poloidal Fourier modes.

nextcur: int

Number of external coil currents.

nfp: int

Number of toroidal field periods.

niter: int

Maximum number of force-balance iterations allowed.

ns: int

Number of radial grid points.

ntor: int

Number of toroidal Fourier modes.

over_r: jt.Float[np.ndarray, 'n_surfaces']

<tau / R> / V’ on half-grid.

pcurr_type: ProfileType

Parametrization of toroidal current profile (copied from input).

phi: jt.Float[np.ndarray, 'n_surfaces']

Enclosed toroidal magnetic flux phi on the full-grid.

phipf: jt.Float[np.ndarray, 'n_surfaces']

Radial derivative of enclosed toroidal magnetic flux phi’ on the full-grid.

phips: jt.Float[np.ndarray, 'n_surfaces']

Radial derivative of enclosed toroidal magnetic flux phi’ on the half-grid.

piota_type: ProfileType

Parametrization of iota profile (copied from input).

pmass_type: ProfileType

Parametrization of mass/pressure profile (copied from input).

pres: jt.Float[np.ndarray, 'n_surfaces']

Kinetic pressure p on the half-grid.

presf: jt.Float[np.ndarray, 'n_surfaces']

Kinetic pressure p on the full-grid.

q_factor: jt.Float[np.ndarray, 'n_surfaces']

Safety factor 1/iota on the full-grid.

raxis_cc: jt.Float[np.ndarray, 'ntor_plus_1']

Fourier coefficients of R(phi) of the magnetic axis geometry.

rbtor: float

Poloidal ribbon current at the plasma boundary.

rbtor0: float

Poloidal ribbon current at the axis.

rmax_surf: float

Maximum R on the plasma boundary over all grid points.

rmin_surf: float

Minimum R on the plasma boundary over all grid points.

rmnc: jt.Float[np.ndarray, 'mn_mode n_surfaces']

Fourier coefficients for R of the geometry of the flux surfaces on the full- grid.

save(out_path)

Save contents in NetCDF3 format.

This is the format used by Fortran VMEC implementations and the one expected by SIMSOPT.

Parameters:

out_path (str | Path)

Return type:

None

signgs: int

Sign of the Jacobian of the coordinate transform between flux coordinates and cylindrical coordinates.

specw: jt.Float[np.ndarray, 'n_surfaces']

Spectral width M on the full-grid.

version_: float

Version number of VMEC, that this VMEC++ wout file is compatible with.

Some codes change how they interpret values in the wout file depending on this number. (E.g. COBRAVMEC checks if >6 or not)

volavgB: float

Volume-averaged magnetic field strength.

volume: typing.Annotated[float, pydantic.Field(alias='volume_p')]

Plasma volume.

property volume_p

The attribute is called volume_p in the Fortran wout file, while simsopt.mhd.Vmec.wout uses volume.

We expose both.

vp: jt.Float[np.ndarray, 'n_surfaces']

Differential volume V’ on half-grid.

wb: float

volume integral of |B|^2/(2 mu0).

Type:

Magnetic energy

wdot: jt.Float[np.ndarray, 'time']

Evolution of the MHD energy decay along the run.

wp: float

volume integral of p.

Type:

Kinetic energy

xm: SerializeIntAsFloat[jt.Int[np.ndarray, 'mn_mode']]

Poloidal mode numbers m for the Fourier coefficients in the state vector.

xm_nyq: SerializeIntAsFloat[jt.Int[np.ndarray, 'mn_mode_nyq']]

Poloidal mode numbers m for the Fourier coefficients in the Nyquist- quantities.

xn: SerializeIntAsFloat[jt.Int[np.ndarray, 'mn_mode']]

Toroidal mode numbers times number of toroidal field periods n * nfp for the Fourier coefficients in the state vector.

xn_nyq: SerializeIntAsFloat[jt.Int[np.ndarray, 'mn_mode_nyq']]

Toroidal mode numbers times number of toroidal field periods n * nfp for the Fourier coefficients in the Nyquist-quantities.

zaxis_cs: jt.Float[np.ndarray, 'ntor_plus_1']

Fourier coefficients of Z(phi) of the magnetic axis geometry.

zmax_surf: float

Maximum Z on the plasma boundary over all grid points.

zmns: jt.Float[np.ndarray, 'mn_mode n_surfaces']

Fourier coefficients for Z of the geometry of the flux surfaces on the full- grid.

vmecpp.run(input, magnetic_field=None, *, max_threads=None, verbose=True, restart_from=None)

Run VMEC++ using the provided input. This is the main entrypoint for both fixed- and free-boundary calculations.

Parameters:

  • input (VmecInput) – a VmecInput instance, corresponding to the contents of a classic VMEC input file

  • magnetic_field (Optional[MagneticFieldResponseTable]) – if present, VMEC++ will pass the magnetic field object in memory instead of reading it from an mgrid file (only relevant in free-boundary runs).

Keyword Arguments:

  • max_threads – maximum number of threads that VMEC++ should spawn. The actual number might still be lower that this in case there are too few flux surfaces to keep these many threads busy. If None, a number of threads equal to the number of logical cores is used.

  • verbose – if True, VMEC++ logs its progress to standard output.

  • restart_from – if present, VMEC++ is initialized using the converged equilibrium from the provided VmecOutput. This can dramatically decrease the number of iterations to convergence when running VMEC++ on a configuration that is very similar to the restart_from equilibrium.

Return type:

VmecOutput

Example

>>> import vmecpp
>>> path = "examples/data/solovev.json"
>>> vmec_input = vmecpp.VmecInput.from_file(path)
>>> output = vmecpp.run(vmec_input, verbose=False, max_threads=1)
>>> round(output.wout.b0, 14) # Exact value may differ by C library
0.20333137113443
Parameters:

Submodules