Usage =============== Known configurations ^^^^^^^^^^^^^^^^^^^^ ``pyQSC`` has several built-in stellarator configurations that can be called using the function :func:`Qsc.from_paper()`. For example, if we wanted to use the second order configuration from section 5.2 of [LandremanSengupta2019]_, we can simply call .. code-block:: from qsc import Qsc stel = Qsc.from_paper('r2 section 5.2') pyQSC has all the first order configurations from [LandremanSenguptaPlunk2019]_, all the second order configurations from [LandremanSengupta2019]_, the precise quasisymmetric configurations of [LandremanPaul2022]_, and the second order configurations in [Landreman2022]_. See :obj:`Qsc.configurations` for the list of these available pre-defined configurations, and see the documentation of :func:`Qsc.from_paper()` for more details. Alternatively, a configuration generated by the `C++ version of QSC `_ can be obtained using the function .. code-block:: from qsc import Qsc stel = Qsc.from_cxx(filename) where ``filename`` is the output file of the C++ version of QSC. New configurations ^^^^^^^^^^^^^^^^^^ A minimal quasisymmetric configuration can be created using the following four parameters: the cosine components of the axis radial component ``rc``, the sine components of the axis vertical component ``zs``, the number of field periods ``nfp`` and the scalar parameter ``etabar`` for the first order magnetic field. The following example creates the ``r1 section 5.1`` configuration using only these four parameters: .. code-block:: from qsc import Qsc stel = Qsc(rc=[1, 0.045], zs=[0, -0.045], nfp=3, etabar=-0.9) The following example creates the second order configuration of ``r2 section 5.4``. As a second order configuration, besides the first order input parameters, it needs to be specified as ``order="r2"``, and it takes one more input parameter: the scalar parameter ``B2c`` for the second order magnetic field. .. code-block:: from qsc import Qsc stel = Qsc(rc=[1, 0.155, 0.0102], zs=[0, 0.154, 0.0111], nfp=2, etabar=0.64, order='r2', B2c=-0.00322) In the examples above, only stellarator-symmetric configurations in vacuum are created. The extra parameters in pyQSC that need to be specified for non-stellarator-symmetric configurations are specified in `Input parameters`_. For a configuration with finite toroidal current on-axis, you can specify the parameter ``I2`` (the second derivative of the current with respect to the radial variable ``r``). Also, at second order, it is possible to specify a value for ``p2`` (the second derivative of the pressure with respect to the radial variable ``r``, usually negative) therefore creating a finite-:math:`\beta` configuration. The resolution used in pyQSC is controlled using the parameter ``nphi`` which is set by default as ``nphi=61``. Simple Demo ^^^^^^^^^^^ In this demo, we create a second order configuration and evaluate a few of its parameters. We also plot a surface shape at a constant toroidal magnetic flux (flux surface) and plot many of the relevant parameters for the near-axis construction. The file associated with this demo is located in the ``examples`` folder. .. code-block:: from qsc import Qsc stel = Qsc(rc=[1, 0.09], zs=[0, -0.09], nfp=2, etabar=0.95, I2=0.9, order='r2', B2c=-0.7, p2=-600000.) print(stel.iota) # Rotational transform on-axis for this configuration print(stel.d2_volume_d_psi2) # Magnetic well V''(psi) print(stel.DMerc_times_r2) # Mercier criterion parameter DMerc multiplied by r^2 print(stel.min_L_grad_B) # Scale length associated with the grad grad B tensor print(stel.grad_grad_B_inverse_scale_length) # Scale length associated with the grad grad B tensor stel.plot_boundary() # Plot the flux surface shape at the default radius r = 0.1 stel.plot() # Plot relevant near axis parameters Input parameters ^^^^^^^^^^^^^^^^ Besides the input parameters of ``pyQSC`` listed above, there are other input parameters related to stellarator-symmetry and to the choice of vacuum or non-vacuum configurations. By order of appearance in the ``Qsc`` function, the possible input parameters to pyQSC are: - rc: the cosine components of the axis radial component - zs: the sine components of the axis vertical component - rs: the sine components of the axis radial component - zc: the cosine components of the axis vertical component - nfp: the number of field periods - etabar: a scalar that specifies the strength of the first order magnetic field modulus - sigma0: the value of the function sigma at phi=0, which is 0 for stellarator-symmetry - B0: the strength of the magnetic field on-axis - I2: the second derivative of the current with respect to the radial variable ``r`` - sG: sign of the Boozer function G - spsi: sign of the toroidal flux function Psi - nphi: toroidal resolution specifying the number of points in a grid along the axis - B2s: a scalar that specifies the strength of the sine component of the second order magnetic field modulus, 0 for stellarator-symmetry - B2c: a scalar that specifies the strength of the cosine component of the second order magnetic field modulus - p2: the second derivative of the pressure with respect to the radial variable ``r``, usually negative - order: a string that specifies the order of the expansion, "r1", "r2" or "r3". For "r3" only the X3c1, Y3c1 and Y3s1 components are calculated (see section 3 of [LandremanSengupta2019]_) Using with SIMSOPT ^^^^^^^^^^^^^^^^^^ An example of the usage of ``pyQsc`` with the optimization code ``SIMSOPT`` is shown in the examples folder in the file ``simsopt_demo.py``. .. [LandremanSenguptaPlunk2019] Landreman, Sengupta, and Plunk, *Journal of Plasma Physics* **85**, 905850103 (2019). .. [LandremanSengupta2019] Landreman and Sengupta, *Journal of Plasma Physics* **85**, 815850601 (2019). .. [LandremanPaul2022] Landreman and Paul, *Physical Review Letters* **128**, 035001 (2022). .. [Landreman2022] Landreman, *Journal of Plasma Physics* **88**, 905880616 (2022).