Merge pull request #63 from pabloprf/development

Release of working version of MITIM 3.0.0

Author: pabloprf

docs/capabilities/optimization.rst

@@ -36,14 +36,15 @@ For this tutorial we will need the following modules:
 
    import torch
    import numpy as np
+   from pathlib import Path
    from mitim_tools.opt_tools     import STRATEGYtools
 
 Select the location of the MITIM namelist (see :ref:`Understanding the MITIM namelist` to understand how to construct the namelist file) and the folder to work on:
 
 .. code-block:: python
 
-   folder    = 'MITIM-fusion/tests/scratch/mitim_tut/'
-   namelist  = 'MITIM-fusion/templates/main.namelist.json'
+   folder    = Path('MITIM-fusion/tests/scratch/mitim_tut')
+   namelist  = Path('MITIM-fusion/templates/main.namelist.json')
 
 Then create your custom optimization object as a child of the parent ``STRATEGYtools.opt_evaluator`` class.
 You only need to modify what operations need to occur inside the ``run()`` (where operations/simulations happen) and ``scalarized_objective()`` (to define what is the target to maximize) methods.
@@ -58,11 +59,11 @@ In this example, we are using ``x**2`` as our function with a 2% evaluation erro
          # ----------------------------------------
 
          # Problem description (rest of problem parameters are taken from namelist)
-         self.optimization_options["dvs"] = ["x"]
-         self.optimization_options["dvs_min"] = [0.0]
-         self.optimization_options["dvs_max"] = [20.0]
+         self.optimization_options["problem_options"]["dvs"] = ["x"]
+         self.optimization_options["problem_options"]["dvs_min"] = [0.0]
+         self.optimization_options["problem_options"]["dvs_max"] = [20.0]
 
-         self.optimization_options["ofs"] = ["z", "zval"]
+         self.optimization_options["problem_options"]["ofs"] = ["z", "zval"]
          self.name_objectives = ["zval_match"]
 
       def run(self, paramsfile, resultsfile):
@@ -80,7 +81,7 @@ In this example, we are using ``x**2`` as our function with a 2% evaluation erro
          self.write(dictOFs, resultsfile)
 
       def scalarized_objective(self, Y):
-         ofs_ordered_names = np.array(self.optimization_options["ofs"])
+         ofs_ordered_names = np.array(self.optimization_options["problem_options"]["ofs"])
 
          of = Y[..., ofs_ordered_names == "z"]
          cal = Y[..., ofs_ordered_names == "zval"]
@@ -100,12 +101,12 @@ Then, create an object from the previously defined class:
 
    Note that at this point, you can pass any parameter that you want, just changing the ``__init__()`` method as appropriate.
 
-Now we can create and launch the MITIM optimization process from the beginning (i.e. ``restart = True``):
+Now we can create and launch the MITIM optimization process from the beginning (i.e. ``cold_start = True``):
 
 .. code-block:: python
 
-   PRF_BO = STRATEGYtools.PRF_BO( opt_fun1D, restartYN = True )
-   PRF_BO.run()
+   MITIM_BO = STRATEGYtools.MITIM_BO( opt_fun1D, cold_startYN = True )
+   MITIM_BO.run()
 
 Once finished, we can plot the results easily with:
 

docs/capabilities/shell_scripts.rst

@@ -0,0 +1,37 @@
+Shell Scripts
+====
+To run available shell scripts, go to your temineral, type the name of the script, and any required arguments. For the plotting scripts, usually the 
+path to the folder in which the run was done is required. To see more information about the script including required arguments: 
+
+.. code-block:: bash
+
+    script_name --help
+
+The following shell scripts are available in the MITIM-fusion repository:
+
+**Plotting tools**
+
+- mitim_plot_gacode
+- mitim_plot_tgyro
+- mitim_plot_tglf
+- mitim_plot_cgyro
+- mitim_plot_eq
+- mitim_plot_transp
+- mitim_plot_opt
+- mitim_plot_portals
+- mitim_plot_maestro
+
+**TRANSP**
+
+- mitim_trcheck
+- mitim_trcheck_p 
+- mitim_trclean
+- mitim_trlook 
+- mitim_run_transp
+
+**Miscellaneous**
+
+- mitim_run_tglf
+- mitim_slurm 
+- mitim_compare_nml
+- mitim_scp

docs/capabilities/standalone.rst

@@ -7,4 +7,5 @@ Standalone Capabilities
    tglf_capabilities
    tgyro_capabilities
    transp_capabilities
-   misc_capabilities
+   misc_capabilities
+   shell_scripts

docs/capabilities/tglf_capabilities.rst

@@ -48,32 +48,33 @@ For this tutorial we will need the following modules:
 
 .. code-block:: python
 
+    from pathlib import Path
     from mitim_tools.gacode_tools import TGLFtools
 
 Select the location of the input.gacode file to start the simulation from. You should also select the folder where the simulation will be run:
 
 .. code-block:: python
 
-    inputgacode_file = 'MITIM-fusion/tests/data/input.gacode'
-    folder           = 'MITIM-fusion/tests/scratch/tglf_tut/'
+    inputgacode_file = Path('MITIM-fusion/tests/data/input.gacode')
+    folder           = Path('MITIM-fusion/tests/scratch/tglf_tut')
 
 The TGLF class can be initialized by providing the radial location (in square root of normalized toroidal flux, ``rho``) to run. Note that the values are given as a list, and several radial locations can be run at once:
 
 .. code-block:: python
 
     tglf = TGLFtools.TGLF(rhos=[0.5, 0.7])
 
-To generate the input files (input.tglf) to TGLF at each radial location, MITIM needs to run a few commands to correctly map the quantities in the input.gacode file to the ones required by TGLF. This is done automatically with the ``prep()`` command. Note that MITIM has a *only-run-if-needed* philosophy and if it finds that the input files to TGLF already exist in the working folder, the preparation method will not run any command, unless a ``restart = True`` argument is provided.
+To generate the input files (input.tglf) to TGLF at each radial location, MITIM needs to run a few commands to correctly map the quantities in the input.gacode file to the ones required by TGLF. This is done automatically with the ``prep()`` command. Note that MITIM has a *only-run-if-needed* philosophy and if it finds that the input files to TGLF already exist in the working folder, the preparation method will not run any command, unless a ``cold_start = True`` argument is provided.
 
 .. code-block:: python
 
-    cdf = tglf.prep(folder,inputgacode=inputgacode_file,restart=False )
+    cdf = tglf.prep(folder,inputgacode=inputgacode_file,cold_start=False )
 
 .. tip::
 
     The ``.prep()`` method, when applied to a case that starts with an input.gacode file, launches a `TGYRO` run for a "zero" iteration to generate *input.tglf* at specific ``rho`` locations from the *input.gacode*. This method to generate input files is inspired by how the `OMFIT framework <https://omfit.io/index.html>`_ works.
 
-Now, we are ready to run TGLF. Once the ``prep()`` command has finished, one can run TGLF with different settings and assumptions. That is why, at this point, a sub-folder name for this specific run can be provided. Similarly to the ``prep()`` command, a ``restart`` flag can be provided.
+Now, we are ready to run TGLF. Once the ``prep()`` command has finished, one can run TGLF with different settings and assumptions. That is why, at this point, a sub-folder name for this specific run can be provided. Similarly to the ``prep()`` command, a ``cold_start`` flag can be provided.
 The set of control inputs to TGLF (like saturation rule, electromagnetic effects, etc.) are provided in two ways.
 First, the argument ``TGLFsettings`` indicates the base case to start with.
 The user is referred to ``templates/input.tglf.models.json`` to understand the meaning of each setting, and ``templates/input.tglf.controls`` for the default setup.
@@ -82,17 +83,17 @@ For example, the following two commands will run TGLF with saturation rule numbe
 
 .. code-block:: python
 
-    tglf.run( subFolderTGLF = 'yes_em_folder/', 
+    tglf.run( subFolderTGLF = 'yes_em_folder', 
               TGLFsettings  = 5,
               extraOptions  = {},
-              restart       = False )
+              cold_start       = False )
 
     tglf.read( label = 'yes_em' )
 
-    tglf.run( subFolderTGLF = 'no_em_folder/', 
+    tglf.run( subFolderTGLF = 'no_em_folder', 
               TGLFsettings  = 5,
               extraOptions  = {'USE_BPER':False},
-              restart       = False )
+              cold_start       = False )
 
     tglf.read( label = 'no_em' )
 
@@ -123,10 +124,11 @@ If instead of an input.gacode, you have a TRANSP .CDF file (``cdf_file``) and wa
 
 .. code-block:: python
 
+    from pathlib import Path
     from mitim_tools.gacode_tools import TGLFtools
 
-    cdf_file = 'MITIM-fusion/tests/data/12345.CDF'
-    folder   = 'MITIM-fusion/tests/scratch/tglf_tut/'
+    cdf_file = Path('MITIM-fusion/tests/data/12345.CDF')
+    folder   = Path('MITIM-fusion/tests/scratch/tglf_tut')
 
     tglf     = TGLFtools.TGLF(  cdf    = cdf_file,
                                 rhos   = [0.5,0.7],
@@ -137,7 +139,7 @@ Similarly as in the previous section, you need to run the ``prep()`` command, bu
 
 .. code-block:: python
 
-    cdf = tglf.prep(folder,restart=False)
+    cdf = tglf.prep(folder,cold_start=False)
 
 .. note::
 
@@ -158,11 +160,12 @@ If you have a input.tglf file already, you can still use this script to run it.
 
 .. code-block:: python
 
+    from pathlib import Path
     from mitim_tools.gacode_tools import TGLFtools
 
-    inputgacode_file = 'MITIM-fusion/tests/data/input.gacode'
-    folder           = 'MITIM-fusion/tests/scratch/tglf_tut/'
-    inputtglf_file   = 'MITIM-fusion/tests/data/input.tglf'
+    inputgacode_file = Path('MITIM-fusion/tests/data/input.gacode')
+    folder           = Path('MITIM-fusion/tests/scratch/tglf_tut')
+    inputtglf_file   = Path('MITIM-fusion/tests/data/input.tglf')
 
     tglf = TGLFtools.TGLF()
     tglf.prep_from_tglf( folder, inputtglf_file, input_gacode = inputgacode_file )
@@ -180,10 +183,11 @@ The rest of the workflow is identical, including ``.run()``, ``.read()`` and ``.
 
     .. code-block:: python
 
+        from pathlib import Path
         from mitim_tools.gacode_tools import TGLFtools
 
-        folder           = 'MITIM-fusion/tests/scratch/tglf_tut/yes_em_folder/'
-        inputtglf_file   = 'MITIM-fusion/tests/data/input.tglf'
+        folder           = Path('MITIM-fusion/tests/scratch/tglf_tut/yes_em_folder')
+        inputtglf_file   = Path('MITIM-fusion/tests/data/input.tglf')
 
         tglf = TGLFtools.TGLF()
         tglf.prep_from_tglf( folder, inputtglf_file )

docs/capabilities/tgyro_capabilities.rst

@@ -21,14 +21,15 @@ For this tutorial we will need the following modules:
 
 .. code-block:: python
 
+	from pathlib import Path
 	from mitim_tools.gacode_tools import TGYROtools,PROFILEStools
 
 Select the location of the input.gacode file to start the simulation from. You should also select the folder where the simulation will be run:
 
 .. code-block:: python
 
-	gacode_file = 'MITIM-fusion/tests/data/input.gacode'
-	folder      = 'MITIM-fusion/tests/scratch/tgyro_tut/'
+	gacode_file = Path('MITIM-fusion/tests/data/input.gacode')
+	folder      = Path('MITIM-fusion/tests/scratch/tgyro_tut')
 
 Create a PROFILES class from the input.gacode file:
 
@@ -76,7 +77,7 @@ Now TGYRO can be run:
 
 .. code-block:: python
 
-    tgyro.run( subFolderTGYRO        = 'run1/',      
+    tgyro.run( subFolderTGYRO        = 'run1',      
                iterations            = iterations,
                special_radii         = rhos,
                PredictionSet         = PredictionSet,
@@ -113,10 +114,11 @@ Create a profiles class with the `input.gacode` file that TGYRO used to run and
 
 .. code-block:: python
 
+	from pathlib import Path
 	from mitim_tools.gacode_tools import TGYROtools,PROFILEStools
 
-	gacode_file = 'MITIM-fusion/tests/data/input.gacode'
-	folder      = 'MITIM-fusion/tests/scratch/tgyro_tut/run1/'
+	gacode_file = Path('MITIM-fusion/tests/data/input.gacode')
+	folder      = Path('MITIM-fusion/tests/scratch/tgyro_tut/run1')
 
 	profiles    = PROFILEStools.PROFILES_GACODE(gacode_file)
 	tgyro_out   = TGYROtools.TGYROoutput(folder,profiles=profiles)

docs/capabilities/transp_capabilities.rst

@@ -22,32 +22,33 @@ For this tutorial we will need the following modules:
 .. code-block:: python
 
 	import os
+	from pathlib import Path
 	from mitim_tools.transp_tools import TRANSPtools
 
 TRANSP runs are very personal and specific to each tokamak and plasma, as diagnostic availability strongly varies and namelist settings are not standarized.
 For this reason, this workflow assumes that a folder exists with all the plasma information (UFILES) and namelist required to run TRANSP:
 
 .. code-block:: python
 
-	folder_original = 'MITIM-fusion/tests/data/FolderTRANSP/'
-	folder 			= "MITIM-fusion/tests/scratch/transp_tut/"
-	os.system(f'rm -r {folder}')
-	os.system(f'cp -r {folder_original} {folder}')
+	folder_original = Path("MITIM-fusion/tests/data/FolderTRANSP/")
+	folder 			= Path("MITIM-fusion/tests/scratch/transp_tut/")
+	os.system(f"rm -r {folder}")
+	os.system(f"cp -r {folder_original} {folder}")
 
 First, one would initialize the TRANSP class with the given folder and the tokamak name:
 
 .. code-block:: python
 
-	tokamak = 'CMOD'
+	tokamak = "CMOD"
 	transp  = TRANSPtools.TRANSP( folder, tokamak )
 
 Then, select a shotnumber and run name, such that the TRANSP simulation will have the complete name `shotnumber+runname`, and the MPI settings for the TRANSP run:
 
 .. code-block:: python
 
-	shotnumber  = '12345'
-	runname     = 'X01'
-	mpisettings = { 'trmpi': 1, 'toricmpi': 64, 'ptrmpi': 1 }
+	shotnumber  = "12345"
+	runname     = "X01"
+	mpisettings = { "trmpi": 1, "toricmpi": 64, "ptrmpi": 1 }
 
 	transp.defineRunParameters( shotnumber+runname, shotnumber, mpisettings = mpisettings )
 

docs/capabilities/vitals_capabilities.rst

@@ -23,23 +23,23 @@ For this tutorial we will need the following modules and the folder to run VITAL
 .. code-block:: python
 
 	import numpy as np
-
+	from pathlib import Path
 	from mitim_tools.gacode_tools import TGLFtools
 	from mitim_modules.vitals     import VITALSmain
 	from mitim_tools.opt_tools    import STRATEGYtools
 
-	folder = 'MITIM-fusion/tests/scratch/vitals_tut/'
+	folder = Path('MITIM-fusion/tests/scratch/vitals_tut')
 
 As a starting point of VITALS, you need to prepare and run TGLF for the base case (please follow the :ref:`TGLF` tutorial for more details):
 
 .. code-block:: python
 
-	inputgacode_file = 'MITIM-fusion/tests/data/input.gacode'
+	inputgacode_file = Path('MITIM-fusion/tests/data/input.gacode')
 	rho              = 0.5
 	
 	tglf = TGLFtools.TGLF( rhos = [ rho ] )
 	cdf = tglf.prep( folder, inputgacode = inputgacode_file)
-	tglf.run( subFolderTGLF = 'run_base/', TGLFsettings = 5)
+	tglf.run( subFolderTGLF = 'run_base', TGLFsettings = 5)
 	tglf.read( label = 'run_base' )
 
 
@@ -84,7 +84,7 @@ At this point, the TGLF class is ready to go into VITALS. One can give the ``tgl
 
 .. code-block:: python
 
-	tglf_file = folder + 'tglf_base.pkl'
+	tglf_file = folder / 'tglf_base.pkl'
 	tglf.save_pkl(tglf_file)
 
 
@@ -114,7 +114,7 @@ Then, as it the case for all optimization problems in MITIM, you must create a f
 
 	# Option 2: Use a curated VITALS namelist and only modify some requested values
 	vitals_fun = VITALSmain.vitals( folder )
-	vitals_fun.optimization_options['BO_iterations'] = 5
+	vitals_fun.optimization_options['convergence_options']['maximum_iterations'] = 5
 
 Once the VITALS object has been created, parameters such as the TGLF control inputs can be chosen:
 
@@ -137,16 +137,16 @@ We are now ready to prepare the VITALS class. Here we have two options:
 	# Option 2. Pass the tglf pickled file
 	vitals_fun.prep( tglf_file, rho, ofs, dvs, dvs_min, dvs_max, classLoaded = False )
 
-Now we can create and launch the MITIM optimization process from the beginning (i.e. ``restart = True``):
+Now we can create and launch the MITIM optimization process from the beginning (i.e. ``cold_start = True``):
 
 .. code-block:: python
 
-	mitim_bo = STRATEGYtools.PRF_BO(vitals_fun, restartYN = True )
+	mitim_bo = STRATEGYtools.MITIM_BO(vitals_fun, cold_start = True )
 	mitim_bo.run()
 
 .. note::
 
-	If the user wants to run VITALS as a slurm job in a cluster, it is recommended that the keyword argument ``askQuestions = False`` is passed to ``PRF_BO()``.
+	If the user wants to run VITALS as a slurm job in a cluster, it is recommended that the keyword argument ``askQuestions = False`` is passed to ``MITIM_BO()``.
 
 3. VITALS Interpretation 
 ------------------------

docs/installation.rst

@@ -68,9 +68,18 @@ There are different options to handle this config file.
       from mitim_tools import config_manager
       config_manager.set(file_location)
 
-Apart from machine configurations, ``preferences`` in ``config_user.json`` also includes a ``verbose_level`` flag, which indicates the amount of messages that are printed to the terminal when running MITIM.
-For debugging purposes, it is recommended a maximum verbose level of ``5``.
-For production runs, a minimum verbose level of ``1`` is recommended so that you only get important messages.
+Apart from machine configurations, ``preferences`` in ``config_user.json`` also includes a ``verbose_level`` flag, which indicates the amount of messages that are printed to the terminal when running MITIM:
+
+.. code-block:: console
+   
+   5: everything (normal prints + information prints + warning prints + questions + optimization progress)
+   4: information prints + warning prints + questions + optimization progress
+   3: information prints + warning prints + questions
+   2: warning prints + questions
+   1: warning prints
+   0: nothing
+
+
 ``preferences`` also allows a ``dpi_notebook`` value (in percent from standard), which should be adjusted for each user's screen configuration if the MITIM notebook figures are too small or too large.
 
 This is an example of a ``config_user.json`` file that specifies that TGLF should be run in the *eofe7.mit.edu* machine and TGYRO in the *perlmutter.nersc.gov* machine.