From b0fe0a6c43a26e1134e028a29488109060aa0251 Mon Sep 17 00:00:00 2001
From: Andreas Wingen <wingen@fusion.gat.com>
Date: Tue, 5 Mar 2024 13:56:34 -0800
Subject: [PATCH] Update to comments and variable descriptions for readthedocs

---
 docs/source/inputFile.rst                     |  3 +-
 source/plasma3DClass.py                       | 67 +++++++++++++++++--
 .../D3DTestCase/batchFile.dat                 | 40 ++++++-----
 3 files changed, 90 insertions(+), 20 deletions(-)

diff --git a/docs/source/inputFile.rst b/docs/source/inputFile.rst
index ee07fd8..755a14b 100644
--- a/docs/source/inputFile.rst
+++ b/docs/source/inputFile.rst
@@ -22,7 +22,8 @@ where X is the machine name.
 .. autofunction:: gyroClass.GYRO.allowed_class_vars    
 .. autofunction:: radClass.RAD.allowed_class_vars    
 .. autofunction:: openFOAMclass.OpenFOAM.allowed_class_vars  
-.. autofunction:: plasma3DClass.plasma3D.allowed_class_vars  
+.. autofunction:: plasma3DClass.plasma3D.allowed_class_vars
+.. autofunction:: plasma3DClass.heatflux3D.allowed_class_vars
 
 
 References:
diff --git a/source/plasma3DClass.py b/source/plasma3DClass.py
index b1852d0..a25b8a1 100644
--- a/source/plasma3DClass.py
+++ b/source/plasma3DClass.py
@@ -56,7 +56,35 @@ def __init__(self):
 		
 	def allowed_class_vars(self):
 		"""
-		These variables are read in from the input file. The call is in engine_class.loadInputs
+		.. Writes a list of recognized class variables to HEAT object
+		.. Used for error checking input files and for initialization
+		.. These variables are read in from the input file. 
+		.. The call is in engine_class.loadInputs
+
+		plasma3D Variables:
+		----------------------------
+
+		:plasma3Dmask:  boolean that determines if 3D plasmas should be turned on
+		  If True, uses M3DC1 equilibrium
+		:itt: integer number of toroidal iterations for the MAFOT 'heatlaminar_mpi' run
+		:response: integer to select the M3D-C1 time_xxx.h5 file to use. 
+		  For linear M3D-C1, time_001.h5 includes the plasma response and 
+		  time_000.h5 is the vacuum field only
+		:selectField: integer to switch between g-file (-1) or M3D-C1 (2) in MAFOT run
+		:useIcoil: integer to turn on vacuum field perturbation coils, default is 0
+		:sigma: integer to switch between tracing field lines (0), co-passing (+1) or 
+		  counter-passing (-1) particles in MAFOT
+		:charge: integer, charge of particles, -1 for electrons, >0 for ions
+		  ignored for sigma = 0
+		:Ekin: float, inetic energy of particles in keV; ignored for sigma = 0
+		:Lambda: float, ratio of perpendicular to parallel particle velocity
+		  ignored for sigma = 0
+		:Mass: integer, mass number of particles, 1 for electrons and H, 2 for D, 4 for He
+		  ignored for sigma = 0
+		:loadHF: boolean, True means load previous heat flux results instead of 
+		  running MAFOT, False means run MAFOT
+		:loadBasePath: string, Path for find previous results if loadHF is True
+		:NCPUs: integer, number of CPUs to use in MAFOT, default is 10
 		"""
 		self.allowed_vars = ['plasma3Dmask','itt','response',
 				'selectField','useIcoil','sigma','charge','Ekin','Lambda','Mass','loadHF',
@@ -86,8 +114,10 @@ def initializePlasma3D(self, shot, time, gFile = None, inputDir = None):
 		Set up basic input vars
 		gfile should include the full path and file name
 		inputFile is the main .csv file with input variables
-		cwd is the HEAT data folder on the host machine for this shot and pfc, typically ~/HEAT/data/<machine>_<shot>_<tag>/<time>/<pfcName>
-		inputDir is the folder in the docker container with input files, typically $HEAT_HOME/terminal/<machine>
+		cwd is the HEAT data folder on the host machine for this shot and pfc, 
+		  typically ~/HEAT/data/<machine>_<shot>_<tag>/<time>/<pfcName>
+		inputDir is the folder in the docker container with input files, 
+		  typically $HEAT_HOME/terminal/<machine>
 		"""
 		self.shot = tools.makeInt(shot)
 		self.time = tools.makeInt(time)
@@ -535,7 +565,36 @@ def __init__(self):
     
 	def allowed_class_vars(self):
 		"""
-		These variables are read in from the input file. The call is in engine_class.loadInputs
+		.. Writes a list of recognized class variables to HEAT object
+		.. Used for error checking input files and for initialization
+		.. These variables are read in from the input file. 
+		.. The call is in engine_class.loadInputs
+		
+		heatflux3D Variables:
+		----------------------------
+
+		:Lcmin:  float, maximum scrape-off-layer connection length
+		:lcfs: float, <= 1, normalized poloidal flux of last closed flux surface location
+		:lqCN: float, heat flux layer width lambda_q in mm for Eich profile
+		  same as in 2D, see heatfluxClass.py
+		:S: float, spread width in mm into private flux region for Eich profile
+		  same as in 2D, see heatfluxClass.py
+		:P: float, total power in MW into SOL; same as in 2D, see heatfluxClass.py
+		:radFrac: float, 0<=x<=1, fraction of radiative power
+		  same as in 2D, see heatfluxClass.py
+		:qBG: float, background heat flux in MW/m^2; same as in 2D, see heatfluxClass.py
+		:teProfileData: None (defaults to 2.0) 
+		  or string (Name of Te data file) 
+		  or float (scaler for generic Te profile) 
+		  or comma-separated array (Te data vs psi=linspace(0,1.1,len(Te)))
+		:neProfileData: None (defaults to 0.5) 
+		  or string (Name of ne data file) 
+		  or float (scaler for generic ne profile) 
+		  or comma-separated array (ne data vs psi=linspace(0,1.1,len(ne)))
+		:kappa: float, electron heat conductivity
+		:model: string in [layer, conductive, convective] to select heat flux model 
+		:NCPUs: integer, number of CPUs to use in MAFOT, default is 10
+		  same as in plasma3D class
 		"""
 		self.allowed_vars = ['Lcmin', 'lcfs', 'lqCN', 'S', 'P', 'radFrac', 'qBG', 
 				'teProfileData', 'neProfileData', 'kappa', 'model','NCPUs']
diff --git a/tests/integrationTests/D3DTestCase/batchFile.dat b/tests/integrationTests/D3DTestCase/batchFile.dat
index 5980582..94bb692 100644
--- a/tests/integrationTests/D3DTestCase/batchFile.dat
+++ b/tests/integrationTests/D3DTestCase/batchFile.dat
@@ -1,9 +1,8 @@
-
 #HEAT batchFile
 #For use when running HEAT in terminal / batch mode.  Each line is a new entry.
 #
 # The fist line of every batchFile should be (uncommented):
-# MachFlag, Tag, GEQDSK, CAD, PFC, Input, Output
+# MachFlag, Tag, Shot, TimeStep, GEQDSK, CAD, PFC, Input, Output
 #
 #===Column variables are defined as follows
 # MachFlag: machine specific flag.
@@ -11,17 +10,28 @@
 #
 # Tag:  user specified tag to label the simulation by.  Tags represent
 #       independent HEAT runs.  For time varying discharges with multiple
-#       GEQDSK files, tag should be repeated on multiple lines with the GEQDSK
-#       for each timestep in each line.
+#       GEQDSK files, tag should be repeated on multiple lines with the 
+#       TimeStep column changing.
+#
+# Shot:  pulse number to use for saving HEAT output (MachFlag_Shot).  Default is to
+#        allow for 6 sig figs of shot numbers.  SigFigs can be changed in engineClass
+#        object initialization function call.
+#
+# TimeStep: Timestep that the equilibrium defined in "GEQDSK" column corresponds
+#           to.  GEQDSKs can be named in multiple formats, but the TimeStep in 
+#           this row is what is used by HEAT.  For time varying discharges, tag 
+#           should be repeated on multiple lines with the TimeStep column changing.
+#           Timestep units are [s].  Default is to allow for 9 SigFigs after the
+#           radix, which corresponds to nanosecond resolution (defined in engineClass
+#           initialization function call)
 #
 # GEQDSK:  magnetic equilibrium file (ie EFIT) in GEQDSK format
-#          naming convention is g<shot>.<timestep> where <shot> is the integer
-#          shot number (6 digits) and timestep is the timestep in ms (5 digits).
-#          For example, shot 204118 timestep 50ms would be g204118.00050
+#          Psi should be in units of Wb/rad (divide by 2pi) and the Bt0, Fpol, Psi
+#          and Ip values should reflect COCOS.
 #
 # CAD: CAD file for the tag.  Note that HEAT will use the first CAD file provided
 #      in for each tag.  Subsequent lines in that tag are ignored.  In other words,
-#      there can only be one CAD file per tag.
+#      there can only be one CAD file per tag.  Can be STEP, IGES, or FCStd formats.
 #
 # PFC: PFC file for the tag.  Note that HEAT will use the first PFC file provided
 #      in for each tag.  Subsequent lines in that tag are ignored.  In other words,
@@ -56,16 +66,16 @@
 # <path>/<MachFlag>/PFC
 # <path>/<MachFlag>/Input
 #
-#  Example line for an NSTX-U run:
-#MachFlag, Tag, GEQDSK, CAD, PFC, Input, Output
-#nstx,run1, g204118.00004, IBDH_2tiles.step, PFCs_run1.csv, NSTXU_input.csv, B:hfOpt
+#  Example line for DIII-D run for pulse 154859 at timestep 4300 ms:
+#MachFlag, Tag, Shot, TimeStep, GEQDSK, CAD, PFC, Input, Output
+#d3d, plasma3D, 154859, 4300, g154859.04300, d3d_sector.step, PFCinput.csv, D3D_input.csv, hfOpt
 #
 # And the directory structure would look like this
 # <path>/batchFile.dat
-# <path>/nstx/g204118.00004
-# <path>/nstx/IBDH_2tiles.step
-# <path>/nstx/PFCs_run1.csv
-# <path>/nstx/NSTXU_input.csv
+# <path>/d3d/g154859.04300
+# <path>/d3d/d3d_sector.step
+# <path>/d3d/PFCinput.csv
+# <path>/d3d/D3D_input.csv
 #
 #
 #