************************
* Help-file for CHEASE *
************************

For details, read the published reference:
"The CHEASE code for toroidal MHD equilibria",
H. Luetjens, A. Bondeson and O. Sauter,
Computer Physics Communications 97 (1996) 219


OUTLINE:
#######
I.   Directory and file requirements
II.  Adjusting parameters in the Namelist file
   1.   Scale parameters
   2.   Last closed flux surface parameters
   3.   Pressure profile parameters
   4.   "Current" profile parameters
   5.   Equilibrium transformation parameters
   6.   Ballooning calculation and optimization
   7.   Bootstrap specification
   8.   Mesh densification
   9.   Array-size and precision parameters
III. Data in the Matlab output file



I. Directory and file requirements:
   -------------------------------

  Before analysing the case "CaseID", the user must create
    1) a directory CHEASE in his/her home directory
    2) a directory "CaseID" in the above directory
  and transfer in the CHEASE/"CaseID" directory
    	a) a Namelist file 
           (a default file, to modify, is copied if no Namelist exists)
    	b) a EXPEQ file if some input data are point-by-point specified
    
    
II. Adjusting parameters in the Namelist file:
    -----------------------------------------

II.1. Scale parameters: (page 236)
      
  In CHEASE, length and magnetic field are normalized to reference values:
  	R0EXP = Reference major radius [m]
  	B0EXP = Reference magnetic field [T]
	
  The physical meaning of these parameters is specified by adjusting the value
  of the indices NRSCAL and NTMF0:
  	NRSCAL = 0 -> mean major-radius of plasma-boundary set to 1
  	NRSCAL = 1 -> magnetic-axis major-radius set to 1  
  	NTMF0  = 0 -> diamagnetic function T = 1 at the plasma boundary
 	NTMF0  = 1 -> diamagnetic function T = 1 at the magnetic axis

II.2. Last closed flux surface parameters: (pages 244-245)
      
  Basic parameters:
              |R = R0 + a*cos(p+t*sin(p))*(1+b*cos(p))
    Definition|
              |Z = a*e*sin(p)
    with p the geometric poloidal angle (0/pi on the low/high-field side)
         a the minor radius (R(p=0)-R(p=pi))/2
         R0 the major radius (R(p=0)+R(p=pi))/2
    the latter two being combined in the parameter
      ASPCT = inverse aspect-ratio (a/R0 above)
    with the additional shape-parameters
      ELONG = elongation (e above)
      TRIANG = triangularity (t above)
      BEANS = bean-shape (b above)
      
  The data type is prescribed by the parameter NSURF:
  
    NSURF = 2 -> Racetrack shape
                |R = R0 + a*cos(p+t*sin(p)-x*sin(2p))*(1+b*cos(p))
      Definition|
                |Z = a*e*sin(p+c*sin(2p))
      with the racetrack parameters
        XI = horizontal racetrack parameter (x above)
        CETA = vertical racetrack parameter (c above)
      whose effect can be visualized with the matlab program PlasBound.m
      
    NSURF = 4 -> Up-Down asymmetric shape (SND equilibria)
                |R = R0 + a*cos(p+t*sin(p))*(1+b*cos(p))
      Definition|Z = a*e*f(p)*sin(p)
                |f(p) = 1 + s*d/(d+(sin^2((p-p0)/2)+x)^n)
**************************************************************                
!NOTE THAT THERE IS A MISTAKE ON EQUATION 49 IN THE REFERENCE!
**************************************************************
      with the asymmetry parameters
        THETA0 = X-point poloidal position [rad] (p0 above)
        SGMA = asymmetry amplitude (s above)
        DELTA = asymetry amplitude (d above)
        RNU = asymmetry poloidal extension (n above)
        XI = X-point sharpness (x above)
      whose effect can be visualized with the matlab program PlasBound.m
      
    NSURF = 6 -> Point-by-point data from EQDSK or EXPEQ file
      NEQDSK = 0 for boundary prescribed through file EXPEQ in EXPEQ format
      NEQDSK = 1 for boundary prescribed through file EXPEQ in EQDSK format


II.3. Pressure profile parameters: (pages 246-247)
      
  The dP/dPsi(Flux) profile is prescribed by four possible forms identified by NPPFUN:
  with Psi and Flux the original and normalized poloidal-fluxes:
    Flux=(Psi(edge)-Psi)/(Psi(edge)-Psi(axis))
    
  NPPFUN = 1 (see equation 52) -> Flux polynomial, with:
    NSOUR = polynomial degree (<10)
    AP = polynomial coefficients in ascending order (1-10)
    
  NPPFUN = 2 (see table 13) -> fixed-degree (1,3&2) polynomial
  in 3 intervals with continuity on dP/dPsi and d2P/dPsi2, with:
    NPP = 1 -> polynomial variable = Flux
      AP = polynomial parameters (2 interval boundaries and 5 derivatives)
    NPP = 2 -> polynomial variable = s = sqrt(Flux)
      AP2 = polynomial parameters (2 interval boundaries and 5 derivatives)
      
  NPPFUN = 3 (see table 14) -> dP/dPsi = p0*(1-Flux^b)^a, with:
    AP(1-3) = (p0,a,b)
    
  NPPFUN = 4 -> Point-by-point data from EQDSK or EXPEQ file, with
    NPPF1 = number of flux points
    FCSM = vector of NPPF1 flux points: in terms of sqrt(Flux)
    RPPF = associated vector of pressure gradient: in terms of dP/dPsi
  
II.4. "Current" profile parameters: (pages 247-248)
      
  The "Current" function F(Flux) is identified (3 choices) by the parameter NSTTP:
    NSTTP = 1 -> F = T*dT/dPsi, with T the diamagnetic function (see equation 2)
    NSTTP = 2 -> F = I* the averaged toroidal current density (see equation 7)
    NSTTP = 3 -> F = I|| the averaged parallel current density (see equation 8)
    
  The F(Flux) profile is prescribed by four possible forms identified by NFUNC:
  
    NFUNC = 1 (see equation 52) -> F polynomial, with:
      NSOUR = polynomial degree (<10)
      AT = polynomial coefficients in ascending order (1-10)
      
    NFUNC = 2 (see table 15) -> fixed-degree (1,3&2) polynomial
    in 3 intervals with continuity on dP/dFlux and d2P/dFlux2, with:
      NIPR = 1 -> polynomial variable t = Flux
        AT = polynomial parameters (2 interval boundaries and 5 derivatives)
      NIPR = 2 -> polynomial variable = t = sqrt(Flux)
        AT2 = polynomial parameters (2 interval boundaries and 5 derivatives)
      NIPR = 3 -> polynomial variable = t = sqrt(sqrt(Flux))
        AT3 = polynomial parameters (2 interval boundaries and 5 derivatives)
      NIPR = 4 -> gaussian form : F(Flux) = h*exp(-((Flux-c)/w)^2)
        AT4(1-3) = (c,w,h)
        
    NFUNC = 3 (see table 14) -> F(Flux) = p0*(1-Flux^b)^a, with:
      AT(1-3) = (p0,a,b)
      
    NFUNC = 4 -> Point-by-point data from EQDSK or EXPEQ file
      RFUN = FCSM-associated vector for the "current" function F
      
II.5. Equilibrium transformation parameters: (sections 5.3 and 6.4.4)
      
  NCSCAL = 1 -> equilibrium rescaled with safety factor fixed on one surface
    CSSPEC = selected flux surface, in terms of sqrt(Flux) with Flux define above
    QSPEC = fixed safety factor value
  NCSCAL = 2 -> equilibrium rescaled with fixed plasma current
    CURRT = plasma current (dimensionless units: see above)
  NCSCAL = 3 -> equilibrium rescaled with safety factor fixed on one surface
    CSSPEC = selected flux surface, in terms of the generalized radius (see table 1)
    QSPEC = fixed safety factor value
    
  NTMF0 = 0 -> diamagnetic function T = 1 at the plasma boundary
  NTMF0 = 1 -> diamagnetic function T = 1 at the magnetic axis
  
  NRSCAL = 0 -> mean major-radius of plasma-boundary (geometric axis) set to 1
  NRSCAL = 1 -> magnetic-axis major-radius set to 1
  
II.6. Ballooning calculation and optimization: (page 253, sections 4.1 and  6.4.3)
      
  NBAL = 1 -> flag for ballooning stability calculation
  NCHI = number of poloidal nodes for ballooning stability calculation
  NTURN = number of poloidal turns in calculation of the ballooning integral
  NBLOPT = 1 -> flag for ballooning optimization
    CFBAL = parameter which controls pressure profile following equation 42
    CPRESS = parameter which rescales pressure profile for local and global stability
    
II.7. Bootstrap specification: (sections 4.2 and 6.4.3)
         
  NBSOPT = 1 -> flag for bootstrap specification
    ETAEI = ratio of density to electron temperature length scales
    RZION = ion charge
    NBSTRP = 1 -> prescribed bootstrap current with constant <Jboot.B>/<Jtot.B>
      BSFRAC = prescribed fraction <Jboot.B>/<Jtot.B> (radially constant)
    NBSTRP = 2 -> Psi-dependent prescribed fraction of bootstrap current
      NBSFUN = data type, equivalent to NPPFUN in dP/dPsi definition above
      AFBS = radial profile, equivalent to AP in dP/dPsi-definition above
    
II.8. Mesh densification: (section 6.4.7)
      
  NDIFPS = 1 -> automatic densification of radial mesh for stability,
                with equidistant generalized radius rho (see table 1)
    NPSI = number of points in the radial mesh for stability
  
  NDIFT = 1 -> automatic densification of the poloidal mesh for equilibrium,
               with constant area in poloidal sectors
  NDIFT = 2 -> same, with constant arc length in poloidal sectors at boundary
    NT = number of points in the poloidal mesh for equilibrium
    
  NMESHA = 1 -> user-defined densification of the radial mesh for stability,
                in terms of the normalized poloidal-flux variable sqrt(Flux)
    NPOIDA = number of points where the mesh is densified
    APLACE = NPOIDA densified radial locations, in terms of sqrt(Flux)
    AWIDTH = width of the densification function (NPOIDA values)
    SOLPDA = fraction of the radial mesh not affected by the densification
    
  NMESHA = 2 -> user-defined densification of the radial mesh for stability,
                in terms of fixed (presumably resonant) safety factor values
    NPOIDQ = number of points where the mesh is densified
    QPLACE = NPOIDA densified radial locations, in terms of safety factor values
    QWIDTH = width of the densification function (NPOIDQ values)
    SOLPDA = fraction of the radial mesh not affected by the densification
    
  NMESHD = 1 -> user-defined densification of the poloidal mesh for equilibrium,
                in terms of the geometric poloidal angle (usefull for SND equilibria)
    NPOIDD = number of points where the mesh is densified
    DPLACE = NPOIDA densified poloidal locations, in terms of geometric poloidal angle
    DWIDTH = width of the densification function (NPOIDD values)
    SOLPDD = fraction of the poloidal mesh not affected by the densification
    
II.9. Array-size and precision parameters: (section 6.1) 
      
  NS = number of points in the radial mesh for equilibrium
  NV = number of points in the radial mesh for MARS equilibrium
  NTNOVA = number of points in the poloidal mesh for NOVA, PEST and XTOR
  NINMAP = maximum number of iterations over current profile      
  NINSCA = maximum number of iterations over nonlinearity                 
  EPSLON = required precision for equilibrium solution (see equation 28)      


III. Data in the Matlab output file:
     ------------------------------
In order to produce the Matlab output file chease_#.mat, with # the case
number, the parameter NPLOT in the Namelist_# file must be set to 1.

All the data are in dimensionless units:
  length normalized to R0EXP
  magnetic field normalized to B0EXP
    
III.1. Plotted versus major radius R:
       
  ZABR = major radius (R) vector    
  ZOFR = poloidal flux function Psi
  ZOQR = safety factor Q (see equation 6)
  ZODQR = dQ/dPsi
  ZOSHR = global shear S
  ZOPR = pressure P
  ZOPPR = dP/dPsi
  ZOJR = toroidal current density J_Phi
  ZOIPR = surface-averaged toroidal current-density I* (see equation 7)
  ZOJBR = surface-averaged parallel current-density I|| (see equation 8)
  ZOJPR = <J_tot.B>
  ZOJBSR = <J_boot.B> (see equation 23)
  ZOTR = diamagnetic function T (see equation 2)
  ZOTTR = T*dT/dPsi (see equation 3)
  ZOBETR = poloidal Beta (see table 1)
  ZOTRR = fraction of trapped particles
      
III.2. Plotted versus the flux variable:
       
  ZABS = flux variable (s) vector (see equation 12)
  ZABSM = same as ZABS but on k+1/2 mesh instead of k mesh (first point = magnetic axis)
  ZOARS = generalized radius rho (see table 1)
  ZOQS = safety factor Q (see equation 6)
  ZODQS = dQ/dPsi with Psi the poloidal flux
  ZOSHS = global shear S
  ZOPS = pressure P
  ZOPPS = dP/dPsi with Psi the poloidal flux
  ZOIPS = surface-averaged toroidal current-density I* (see equation 7)
  ZOJBS = surface-averaged parallel current-density I|| (see equation 8)
  ZOJPS = <J_tot.B>
  ZOJBSS = <J_boot.B> (see equation 23)
  ZOTS = diamagnetic function T (see equation 2)
  ZOTTS = T*dT/dPsi (see equation 3)
  ZOBETS = poloidal Beta (see table 1)
  ZOTRS = fraction of trapped particles
  ZBALL = ballooning stability:
          (un)stable if (1)0 (see equation 16)
  ZODIS = Mercier stability index:
          ideal interchange unstable if negative (see equation 19)
  ZODRS = GGJ stability index:
          resistive interchange unstable if negative (see equation 20-21)
  ZOHS = H index of Glasser-Greene-Johnson (see equation 21)   
      
III.3. 2-D plot:
       
  RRISO = R matrix for iso-flux surfaces
  RZISO = Z matrix for iso-flux surfaces
  ZRSUR = R vector for last-closed flux-surface
  ZZSUR = Z vector for last-closed flux-surface
  CR = R matrix for local shear
  CZ = Z matrix for local shear
  RSHEAR = matrix for local-shear on the (CR,CZ) mesh
  ZRCURV = R vector for zero-curvature line
  ZZCURV = Z vector for zero-curvature line
  
  
