omfit-eqdsk 2020.12.2.22.59
omfit_eqdsk
Requires Python: >=3.6

**EQDSK** files used as part of the OMFIT project: https://omfit.io/

Provides:
=========
* read_basic_eq_from_mds
* from_mds_plus
* OMFIT_pcs_shape
* read_basic_eq_from_toksearch
* x_point_search
* x_point_quick_search
* gEQDSK_COCOS_identify
* OMFITeqdsk
* OMFITaeqdsk
* OMFITgeqdsk
* OMFITkeqdsk
* OMFITmeqdsk
* OMFITseqdsk
* fluxSurfaces
* fluxSurfaceTraces
* boundaryShape
* BoundaryShape
* fluxGeo
* rz_miller
* miller_derived

Requires:
=========
* fortranformat>=0.2
* matplotlib>=3.1,!=3.2.1,!=3.2.2
* numpy>=1.12
* omas>=0.67.0
* scipy>=1.0
* uncertainties>=3
* xarray>=0.10.8
* omfit_ascii==2020.12.2.22.59
* omfit_path==2020.12.2.22.59
* omfit_nc==2020.12.2.22.59
* omfit_namelist==2020.12.2.22.59
* omfit_mds==2020.12.2.22.59
* omfit_data==2020.12.2.22.59
* omfit_error==2020.12.2.22.59
* omfit_commonclasses==2020.12.2.22.59

Authors:
=========
https://omfit.io/contributors.html

Documentation:
==============
read_basic_eq_from_mds
----------------------

    Read basic equilibrium data from MDSplus
    This is a lightweight function for reading simple data from all EFIT slices at once without making g-files.

    :param device: str
        The tokamak that the data correspond to ('DIII-D', 'NSTX', etc.)

    :param server: str [Optional, special purpose]
        MDSplus server to draw data from. Use this if you are connecting to a
        server that is not recognized by the tokamak() command, like vidar,
        EAST_US, etc. If this is None, it will be copied from device.

    :param shot: int
        Shot number from which to read data

    :param tree: str
        Name of the MDSplus tree to connect to, like 'EFIT01', 'EFIT02', 'EFIT03', ...

    :param g_file_quantities: list of strings
        Quantities to read from the sub-tree corresponding with the EFIT g-file.
        Example: ['r', 'z', 'rhovn']

    :param a_file_quantities: list of strings
        Quantities to read from the sub-tree corresponding with the EFIT a-file.
        Example: ['area']

    :param measurements: list of strings
        Quantities to read from the MEASUREMENTS tree.
        Example: ['fccurt']

    :param derived_quantities: list of strings
        Derived quantities to be calculated and returned.
        This script understands a limited set of simple calculations: 'time', 'psin', 'psin1d'
        Example: ['psin', 'psin1d', 'time']

    :param other_results: list of strings
        Other quantities to be gathered from the parent tree that holds gEQDSK and aEQDSK.
        Example: ['DATE_RUN']

    :param quiet: bool

    :param get_all_meas: bool
        Fetch measurement signals according to its time basis which includes extra time slices that failed to fit.
        The time 'axis' will be avaliabe in ['mtimes']

    :param toksearch_mds: OMFITtoksearch instance
        An already fetched and loaded OMFITtoksearch object, expected to have
        fetched all of the signals for the mdsValues in this file.

    :param allow_shot_tree_translation: bool
        Allow the real shot and tree to be translated to the fake shot stored in the EFIT tree

    :return: dict
    

from_mds_plus
-------------

    Gathers EFIT data from MDSplus, interpolates to the desired times, and creates a set of g-files from the results.

    Links to EFIT documentation::
        https://fusion.gat.com/theory/Efit                Home
        https://fusion.gat.com/theory/Efitiofiles         List of input/output files
        https://fusion.gat.com/theory/Efitin1             IN1 namelist description (primary input)

    :param device: string
        Name of the tokamak or MDSserver from whence cometh the data.

    :param shot: int
        Shot for which data are to be gathered.

    :param times: numeric iterable
        Time slices to gather in ms, even if working with an MDS server that normally operates in seconds.

    :param exact: bool
        Fail instead of interpolating if the exact time-slices are not available.

    :param snap_file: string
        Description of which EFIT tree to gather from.

    :param time_diff_warning_threshold: float
        Issue a warning if the difference between a requested time slice and the closest time slice in the source EFIT
        exceeds this threshold.

    :param fail_if_out_of_range: bool
        Skip requested times that fail the above threshold test.

    :param get_afile: bool
        gather A-file quantities as well as G-file quantities.

    :param get_mfile: bool
        gather M-file quantities as well as G-file quantities.

    :param show_missing_data_warnings: bool
        Print a warning for each missing item when setting it to a default value. May not be necessary because some
        things in the a-file don't seem very important and are always missing from MDSplus.

    :param debug: bool
        Save intermediate results to the tree for inspection.

    :param quiet: bool

    :param close: bool
        Close each file at each time before going on to the next time

    :return: a dictionary containing a set of G-files in another dictioanry named 'gEQDSK', and, optionally, a set of
        A-files under 'aEQDSK'.
    

OMFIT_pcs_shape
---------------
N/A

read_basic_eq_from_toksearch
----------------------------
N/A

x_point_search
--------------

    Improve accuracy of X-point coordinates by upsampling a region of the fluxmap around the initial estimate

    Needs some sort of initial estimate to define a search region

    :param rgrid: 1d float array
        R coordinates of the grid
    :param zgrid: 1d float array
        Z coordinates of the grid
    :param psigrid: 2d float array
        psi values corresponding to rgrid and zgrid
    :param r_center: float
        Center of search region in r; units should match rgrid. Defaults to result of x_point_quick_search()
    :param z_center: float
        Center of the search region in z.
    :param dr: float
        Half width of the search region in r. Defaults to about 5 grid cells.
    :param dz:
        Half width of the search region in z. Defaults to about 5 grid cells.
    :param zoom: int
        Scaling factor for upsample
    :param kw: additional keywords passed to x_point_quick_search r_center and z_center are not given.
    :return: two element float array
        Higher quality estimate for the X-point R,Z coordinates with units matching rgrid
    

x_point_quick_search
--------------------

    Make a quick and dirty estimate for x-point position to guide higher quality estimation

    The goal is to identify the primary x-point to within a grid cell or so

    :param rgrid: 1d float array
        R coordinates of the grid

    :param zgrid: 1d float array
        Z coordinates of the grid

    :param psigrid: 2d float array
        psi values corresponding to rgrid and zgrid

    :param psi_boundary: float [optional]
        psi value on the boundary; helps distinguish the primary x-point from other field nulls
        If this is not provided, you may get the wrong x-point.

    :param psi_boundary_weight: float
        Sets the relative weight of matching psi_boundary compared to minimizing B_pol.
        1 gives ~equal weight after normalizing Delta psi by grid spacing and r (to make it comparable to B_pol in
        the first place)
        10 gives higher weight to psi_boundary, which might be nice if you keep locking onto the secondary x-point.
        Actually, it seems like the outcome isn't very sensitive to this weight. psi_boundary is an adequate tie
        breaker between two B_pol nulls with weights as low as 1e-3 for some cases, and it's not strong enough to move
        the quick estiamte to a different grid cell on a 65x65 with weights as high as 1e2. Even then, the result is
        still close enough to the True X-point that the higher quality algorithm can find the same answer. So, just
        leave this at 1.

    :param zsign: int
        If you know the X-point you want is on the top or the bottom, you can pass in 1 or -1 to exclude
        the wrong half of the grid.

    :return: two element float array
        Low quality estimate for the X-point R,Z coordinates with units matching rgrid
    

gEQDSK_COCOS_identify
---------------------

    Returns the native COCOS that an unmodified gEQDSK would obey, defined by sign(Bt) and sign(Ip)
    In order for psi to increase from axis to edge and for q to be positive:
    All use sigma_RpZ=+1 (phi is counterclockwise) and exp_Bp=0 (psi is flux/2.*pi)
    We want
    sign(psi_edge-psi_axis) = sign(Ip)*sigma_Bp > 0  (psi always increases in gEQDSK)
    sign(q) = sign(Ip)*sign(Bt)*sigma_rhotp > 0      (q always positive in gEQDSK)
    ::
        ============================================
        Bt    Ip    sigma_Bp    sigma_rhotp    COCOS
        ============================================
        +1    +1       +1           +1           1
        +1    -1       -1           -1           3
        -1    +1       +1           -1           5
        -1    -1       -1           +1           7
    

OMFITeqdsk
----------

    Automatically determine the type of an EFIT file and parse it with the appropriate class.
    It is faster to just directly use the appropriate class. Using the right class also avoids problems because some
    files technically can be parsed with more than one class (no exceptions thrown), giving junk results.

    :param filename: string
        Name of the file on disk, including path

    :param EFITtype: string
        Letter giving the type of EFIT file, like 'g'. Should be in 'gamks'.
        If None, then the first letter in the filename is used to determine the file type
        If this is also not helping, then a brute-force load is attempted

    :param strict: bool
        Filename (not including path) must include the letter giving the file type.
        Prevents errors like using sEQDSK to parse g133221.01000, which might otherwise be possible.

    :param \**kw: Other keywords to pass to the class that is chosen.

    :return: OMFIT*eqdsk instance
    

OMFITaeqdsk
-----------

    class used to interface A files generated by EFIT

    :param filename: filename passed to OMFITascii class

    :param \**kw: keyword dictionary passed to OMFITascii class
    

OMFITgeqdsk
-----------

    class used to interface G files generated by EFIT

    :param filename: filename passed to OMFITascii class

    :param \**kw: keyword dictionary passed to OMFITascii class
    

OMFITkeqdsk
-----------

    class used to interface with K files used by EFIT

    :param filename: filename passed to OMFITascii class

    :param \**kw: keyword dictionary passed to OMFITascii class
    

OMFITmeqdsk
-----------

    class used to interface M files generated by EFIT
    :param filename: filename passed to OMFITascii class

    :param \**kw: keyword dictionary passed to OMFITascii class
    

OMFITseqdsk
-----------

    class used to interface S files generated by EFIT

    :param filename: filename passed to OMFITascii class

    :param \**kw: keyword dictionary passed to OMFITascii class
    

fluxSurfaces
------------

    Trace flux surfaces and calculate flux-surface averaged and geometric quantities
    Inputs can be tables of PSI and Bt or an OMFITgeqdsk file
    

fluxSurfaceTraces
-----------------
N/A

boundaryShape
-------------

    Function used to generate boundary shapes based on `T. C. Luce, PPCF, 55 9 (2013)`
    Direct Python translation of the IDL program /u/luce/idl/shapemaker3.pro

    :param a: minor radius

    :param eps: aspect ratio

    :param kapu: upper elongation

    :param lkap: lower elongation

    :param delu: upper triangularity

    :param dell: lower triangularity

    :param zetaou: upper outer squareness

    :param zetaiu: upper inner squareness

    :param zetail: lower inner squareness

    :param zetaol: lower outer squareness

    :param zoffset: z-offset

    :param upnull: toggle upper x-point

    :param lonull: toggle lower x-point

    :param npts: int
        number of points (per quadrant)

    :param doPlot: plot boundary shape construction

    :param newsq: A 4 element array, into which the new squareness values are stored

    :return: tuple with arrays of r,z,zref

    >> boundaryShape(a=0.608,eps=0.374,kapu=1.920,kapl=1.719,delu=0.769,dell=0.463,zetaou=-0.155,zetaiu=-0.255,zetail=-0.174,zetaol=-0.227,zoffset=0.000,upnull=False,lonull=False,doPlot=True)
    

BoundaryShape
-------------

    Class used to generate boundary shapes based on `T. C. Luce, PPCF, 55 9 (2013)`
    

fluxGeo
-------

    Calculate geometric properties of a single flux surface

    :param inputR: R points

    :param inputZ: Z points

    :param lcfs: whether this is the last closed flux surface (for sharp feature of x-points)

    :param doPlot: plot geometric measurements

    :return: dictionary with geometric quantities
    

rz_miller
---------

    return R,Z coordinates for all flux surfaces from miller geometry coefficients in input.profiles file
    based on gacode/gapy/src/gapy_geo.f90

    :param a: minor radius

    :param R: major radius

    :param kappa: elongation

    :param delta: triandularity

    :param zeta: squareness

    :param zmag: z offset

    :param poloidal_resolution: integer with number of equispaced points in toroidal angle, or array of toroidal angles

    :return: 1D arrays with (R, Z) flux surface coordinates
    

miller_derived
--------------

    Originally adapted by A. Tema from FORTRAN of gacode/shared/GEO/GEO_do.f90

    :param rmin: minor radius

    :param rmaj: major radius

    :param kappa: elongation

    :param delta: triangularity

    :param zeta: squareness

    :param zmag: z magnetic axis

    :param q: safety factor

    :return: dictionary with volume, grad_r0, bp0, bt0