spectre.converters.simsvmec2spectre
===================================

.. py:module:: spectre.converters.simsvmec2spectre

.. autoapi-nested-parse::

   VMEC-to-SPECTRE converter using the simsopt Vmec interface.





Module Contents
---------------

.. py:function:: simsvmec2spectre(vmec_obj, tfluxes=None, nvol=None, mpol=None, ntor=None, inface_current=False, profile_type=None, filename=None, plot=False, angle_fix=True, interface_guess=None, map2disc_kwargs=None)

   Generate a SPECTRE input from a simsopt VMEC equilibrium.

   Reads pressure, rotational-transform or current profiles and the plasma
   boundary from a simsopt :class:`~simsopt.mhd.Vmec` object, discretises
   them onto a set of SPECTRE interfaces, and optionally writes the result to
   a TOML file.

   Supports both VMEC ``input.*`` files (``vmec_obj.indata``) and
   ``wout_*.nc`` output files (``vmec_obj.wout``).  Only ``power_series``
   current profiles are supported.

   Args:
       vmec_obj: simsopt ``Vmec`` instance.
       tfluxes: 1-D array-like of interface toroidal-flux values in (0, 1].
           Mutually exclusive with ``nvol``.  If ``tfluxes[-1] < 1``, the
           outermost SPECTRE interface is interior to the VMEC plasma
           boundary; the boundary coefficients (``rbc``/``zbs``) are then
           replaced with the interpolated geometry at ``tfluxes[-1]``.  This
           requires ``interface_guess`` to be ``'wout'`` or ``'map2disc'``.
       nvol: number of SPECTRE volumes; interfaces are placed uniformly.
           Mutually exclusive with ``tfluxes``.
       mpol: poloidal Fourier resolution.  Defaults to ``vmec_obj.boundary.mpol``.
       ntor: toroidal Fourier resolution.  Defaults to ``vmec_obj.boundary.ntor``.
       inface_current: if ``False`` (default), the toroidal current is placed
           as distributed volume current (``ivolume``); if ``True``, it is
           placed entirely on the interfaces as sheet current (``isurf``).
           Only relevant when the VMEC equilibrium uses a current profile.
           The continuous-to-discrete current mapping is **provisional** — see
           :func:`~spectre.converters.vmec_helpers.distribute_current_to_interfaces`.
       profile_type: ``'iota'`` or ``'current'``, overriding auto-detection.
           When ``None`` (default), the type is inferred from the source:
           ``ncurr`` for ``indata``, or whether ``ai`` is nonzero for ``wout``.
       filename: path for the output TOML file.  If ``None``, no file is
           written and the result is returned only.
       plot: if ``True``, show a figure comparing VMEC continuous profiles
           with the SPECTRE-discretised values.
       angle_fix: if ``True`` (default), apply the θ→-θ handedness correction
           to boundary and interface coefficients (n→-n for m>0, ZBS negated).
           This replaces the need for ``lchangeangle=True`` in the TOML.
           Because θ→-θ reverses the poloidal direction, the poloidal-sense
           scalars are negated to match: the rotational transform (``iota``/
           ``oita``) and the toroidal current (``curtor``, and hence the
           derived ``isurf``/``ivolume``).
           Set to ``False`` only for equilibria that run correctly without
           ``lchangeangle``.
       interface_guess: strategy for generating initial interface geometry.
           ``None`` (default) — no guesses; SPECTRE linearly interpolates
           (``linitialize=1``).
           ``'wout'`` — cubic interpolation of VMEC flux surfaces from a wout
           file (requires the ``Vmec`` object to have been loaded from a
           ``wout_*.nc`` file).
           ``'map2disc'`` — conformal mapping via the ``map2disc`` library;
           works from both ``input.*`` and ``wout_*.nc`` sources.
           When guesses are provided, ``linitialize=0``.
       map2disc_kwargs: optional dict of keyword arguments forwarded to
           :func:`~spectre.converters.compute_guesses_map2disc.compute_interface_guesses_map2disc`
           (e.g. ``{"ntheta": 32, "nzeta": 15, "bcm_m": 4}``).
           Only used when ``interface_guess='map2disc'``.

   Returns:
       Validated :class:`~spectre.file_io.input_parameters.InputParameters`
       pydantic object.

   Raises:
       RuntimeError: if neither ``tfluxes`` nor ``nvol`` is provided.
       RuntimeError: if ``vmec_obj`` has neither ``indata`` nor ``wout``.
       RuntimeError: if the current-profile type is not ``'power_series'``.
       RuntimeError: if ``interface_guess='wout'`` but the Vmec object has no wout.
       ValueError: if ``interface_guess`` is not ``None``, ``'wout'``, or ``'map2disc'``.
       ValueError: if ``tfluxes[-1] < 1`` but ``interface_guess`` is ``None``.