Restructure Python CLI scripts to support bundling in Python packages (eg. PyPi) (OpenFUSIONToolkit#323)

 - Remove legacy Python `print_function` bridges
 - Update documentation

Author: hansec

src/CMakeLists.txt

@@ -489,8 +489,9 @@ if( OFT_BUILD_PYTHON )
     set(OFT_SHARED_LIBS ${ARGV0} ${OFT_SHARED_LIBS} CACHE INTERNAL "package_shared_libs")
   endfunction(oft_add_shared)
   # Library directories
-  add_subdirectory( python/wrappers )
   add_subdirectory( python/OpenFUSIONToolkit )
+  add_subdirectory( python/wrappers )
+  add_subdirectory( python/scripts )
 endif()
 
 ########################

src/docs/ThinCurr/doc_thincurr_dep.md

@@ -20,10 +20,10 @@ mesh definition files that mark the nodes corresponding to a given hole. There a
  will then generate an ordered loop from this list.
 
 Nodesets are stored in the `mesh/NODESET****` fields in native mesh files. These can be converted from nodesets defined via the
-Cubit meshing software, through the Exodus II mesh format, and `convert_cubit.py` or other mesh inputs with suitable interfacing
+Cubit meshing software, through the Exodus II mesh format, and `OFT_convert_cubit.py` or other mesh inputs with suitable interfacing
 scripts.
 
 Closures can also be manually defined using "sidesets" in mesh definition files that mark the triangles where an element should be removed to
 avoid singularities in the system. Sidesets are stored in the `mesh/SIDESET****` fields in native mesh files. These can be
-converted from nodesets defined via the Cubit meshing software, through the Exodus II mesh format, and `convert_cubit.py` or other
+converted from nodesets defined via the Cubit meshing software, through the Exodus II mesh format, and `OFT_convert_cubit.py` or other
 mesh inputs with suitable interfacing scripts.

src/docs/ThinCurr/doc_thincurr_main.md

@@ -36,22 +36,6 @@ The following examples illustrate usage of ThinCurr to perform calculations usin
 
 \section doc_tw_main_settings ThinCurr settings groups
 
-\subsection doc_tw_main_settings_fortran Fortran option groups
-Driver-specific settings groups are defined for each of the programs above (eg. `thincurr_td`), follow links for description
-of available settings.
-
-The following driver-wide settings are also available:
-
-**Option group:** `thincurr_hodlr_options` (see \ref doc_tw_main_hodlr "HODLR")
-|  Option                 |  Description  | Type [dim] |
-|-------------------------|---------------|------------|
-|  `target_size=1500`     |  Target size for mesh partitioning | int |
-|  `aca_min_its=20`       |  Minimum nuber of ACA+ iterations to perfom (if used) | int |
-|  `L_svd_tol=-1.0`       |  SVD tolerance for HODLR compression of \f$ \textrm{L} \f$ matrix (negative to disable) | int |
-|  `L_aca_rel_tol=-1.0`   |  ACA tolerance (relative to SVD) for HODLR compression of \f$ \textrm{L} \f$ matrix (negative to disable) | int |
-|  `B_svd_tol=T`          |  SVD tolerance for HODLR compression of B reconstruction operator (negative to disable) | int |
-|  `B_aca_rel_tol=F`      |  ACA tolerance (relative to SVD) for HODLR compression of B reconstruction operator (negative to disable) | int |
-
 \subsection doc_tw_main_settings_xml XML input settings
 Settings for ThinCurr runs are contained in the `oft->thincurr` element, with the following elements:
   * `eta`: Comma separated values for surface resistivity (\f$ \eta_s = \eta / t \f$) in each region
@@ -74,6 +58,22 @@ Settings for ThinCurr runs are contained in the `oft->thincurr` element, with th
 </oft>
 ```
 
+\subsection doc_tw_main_settings_fortran Fortran option groups
+Driver-specific settings groups are defined for each of the programs above (eg. `thincurr_td`), follow links for description
+of available settings.
+
+The following driver-wide settings are also available:
+
+**Option group:** `thincurr_hodlr_options` (see \ref doc_tw_main_hodlr "HODLR")
+|  Option                 |  Description  | Type [dim] |
+|-------------------------|---------------|------------|
+|  `target_size=1500`     |  Target size for mesh partitioning | int |
+|  `aca_min_its=20`       |  Minimum nuber of ACA+ iterations to perfom (if used) | int |
+|  `L_svd_tol=-1.0`       |  SVD tolerance for HODLR compression of \f$ \textrm{L} \f$ matrix (negative to disable) | int |
+|  `L_aca_rel_tol=-1.0`   |  ACA tolerance (relative to SVD) for HODLR compression of \f$ \textrm{L} \f$ matrix (negative to disable) | int |
+|  `B_svd_tol=T`          |  SVD tolerance for HODLR compression of B reconstruction operator (negative to disable) | int |
+|  `B_aca_rel_tol=F`      |  ACA tolerance (relative to SVD) for HODLR compression of B reconstruction operator (negative to disable) | int |
+
 
 \section doc_tw_main_num Description of numerics
 Currents in ThinCurr are represented in terms of a surface current (\f$ \textbf{J}_s = \int \textbf{J} dt_w = \textbf{J} * t_w \f$),
@@ -210,10 +210,15 @@ correct this two holes must be added, corresponding to loops in each of these tw
 This use of jumps and a single-valued potential to represent a multivalued potential is common practice in numerical methods.
 
 \subsubsection doc_tw_main_holes_def Defining holes
-Holes can be defined using the `ThinCurr_compute_holes.py` script. This script analyzes the toplogy of a given
+Holes can be defined using the `OFT_ThinCurr_holes.py` script. This script analyzes the toplogy of a given
 mesh and automatically locates and defines needed hole elements. This is now the recommended way of defining holes in
 ThinCurr models, although \ref doc_tw_dep_leg_holes "manual definition" is also still supported.
 
+The script should be available in one of two ways depending on the installation/build setup:
+ - If OFT is installed via `pip` or similar, then it should be available via command line as `OFT_ThinCurr_holes` in any environment where OFT is also available (eg. virtual environment)
+ - If OFT is installed any other way, including installation from source, the `OFT_ThinCurr_holes.py` script will be located in the `python` directory of the install or build folder
+
+
 \subsection doc_tw_main_close "Closure" elements
 As stated above the fact that the solution depends only on the gradient and not on the absolute value of \f$ \phi \f$ itself can
 introduce a gauge ambiguity, resulting in redundant degrees of freedom. In the cases considered above this is resolved by keeping
@@ -223,7 +228,7 @@ potential to zero at that point. We call these elements "closure" elements as th
 solveable.
 
 \subsubsection doc_tw_main_close_def Defining closures
-As with holes, closures can also be defined using the `ThinCurr_compute_holes.py` script. This is now the recommended way of defining
+As with holes, closures can also be defined using the `OFT_ThinCurr_holes.py` script. This is now the recommended way of defining
 closures in ThinCurr models, although \ref doc_tw_dep_leg_holes "manual definition" is also still supported.
 
 \subsection doc_tw_main_hodlr Hierarchical Off-Diagonal Low-Rank (HODLR) approximation

src/docs/ThinCurr/thincurr_example1.md

@@ -15,9 +15,9 @@ During the run you will see it report a bunch of general information and then it
 
 # Post processing
 
-Once complete you can now generate XDMF files suitable for visualization of results using the [VisIt](https://visit-dav.github.io/visit-website/index.html) code. This is a two step process. First, rerun the code as above but with `plot_run=T` in the `thincurr_eig_options` group. Once complete, you need to run the `build_xdmf.py` script, which generates XDMF metadata files that tells VisIt how to read the data. This can be done using the following command
+Once complete you can now generate XDMF files suitable for visualization of results using the [VisIt](https://visit-dav.github.io/visit-website/index.html) code. This is a two step process. First, rerun the code as above but with `plot_run=T` in the `thincurr_eig_options` group. Once complete, you need to run the `OFT_build_xdmf.py` script, which generates XDMF metadata files that tells VisIt how to read the data. This can be done using the following command
 
-    python /path/to/oft/bin/build_xdmf.py
+    python /path/to/oft/bin/OFT_build_xdmf.py
 
 Next use VisIt to open the `surf_static.xmf` file, which will contain a series of vector fields named as `J_XX` that correspond to the current distributions of the various eigenstates. If you are running this example remotely and using VisIt locally you will need to copy the `mesh.*.h5`, `scalar_dump.*.h5`, `vector_dump.*.h5`, and `*.xmf` files to your local computer for visualization. The first eigenmode `J_01` should look like the figure below.
 
@@ -88,8 +88,8 @@ set large exodus file on
 export Genesis  "thincurr_ex-plate.g" overwrite block 1
 ```
 
-The file can then be converted to OFT's native mesh format using the `convert_cubit.py` script as
+The file can then be converted to OFT's native mesh format using the `OFT_convert_cubit.py` script as
 
-    python /path/to/OFT/bin/convert_cubit.py --in_file=thincurr_ex-plate.g
+    python /path/to/OFT/bin/OFT_convert_cubit.py --in_file=thincurr_ex-plate.g
 
 which will yield the converted file `thincurr_ex-plate.h5`.

src/docs/ThinCurr/thincurr_example2.md

@@ -21,9 +21,9 @@ Contents of the input files are provided below and in the examples directory und
 
 # Post processing
 
-Once complete you can now generate VisIt files to visualize the solution as above. First, rerun the code as above but with "plot_run=T" in the `thincurr_td_options` group. Once complete, you need to run the `build_xdmf.py` script, which generates XDMF metadata files that tells VisIt how to read the data. This can be done using the following command
+Once complete you can now generate VisIt files to visualize the solution as above. First, rerun the code as above but with "plot_run=T" in the `thincurr_td_options` group. Once complete, you need to run the `OFT_build_xdmf.py` script, which generates XDMF metadata files that tells VisIt how to read the data. This can be done using the following command
 
-    python /path/to/oft/bin/build_xdmf.py
+    python /path/to/oft/bin/OFT_build_xdmf.py
 
 Next use VisIt to open the `surf_out_XXXX.xmf` database, which will contain a series timepoints with the vector field `J`. If you are running this example remotely and using VisIt locally you will need to copy the `mesh.*.h5`, `scalar_dump.*.h5`, `vector_dump.*.h5`, and `*.xmf` files to your local computer for visualization. The solution `J` at the first time point should look like the figure below.
 
@@ -114,8 +114,8 @@ set large exodus file on
 export Genesis  "thincurr_ex-cyl.g" overwrite block 1
 ```
 
-The file can then be converted to OFT's native mesh format using the `convert_cubit.py` script as
+The file can then be converted to OFT's native mesh format using the `OFT_convert_cubit.py` script as
 
-    python /path/to/OFT/bin/convert_cubit.py --in_file=thincurr_ex-cyl.g
+    python /path/to/OFT/bin/OFT_convert_cubit.py --in_file=thincurr_ex-cyl.g
 
 which will yield the converted file `thincurr_ex-cyl.h5`.

src/docs/ThinCurr/thincurr_example3.md

@@ -15,9 +15,9 @@ Contents of the input files are provided below and in the examples directory und
 
 # Post processing
 
-Once complete you can now generate XDMF files suitable for visualization of results using the [VisIt](https://visit-dav.github.io/visit-website/index.html) code. For frequency-response calculations we do not need to do a separate plotting run, so once complete, you just need to run the `build_xdmf.py` script, which generates XDMF metadata files that tells VisIt how to read the data. This can be done using the following command
+Once complete you can now generate XDMF files suitable for visualization of results using the [VisIt](https://visit-dav.github.io/visit-website/index.html) code. For frequency-response calculations we do not need to do a separate plotting run, so once complete, you just need to run the `OFT_build_xdmf.py` script, which generates XDMF metadata files that tells VisIt how to read the data. This can be done using the following command
 
-    python /path/to/oft/bin/build_xdmf.py
+    python /path/to/oft/bin/OFT_build_xdmf.py
 
 Next use VisIt to open the `surf_static.xmf` file, which will contain two vector fields `JRe` and `JIm` that correspond to the current distributions for the real and imaginary components of the solution in the frequency-domain. If you are running this example remotely and using VisIt locally you will need to copy the `mesh.*.h5`, `scalar_dump.*.h5`, `vector_dump.*.h5`, and `*.xmf` files to your local computer for visualization. The real component `JRe` should look like the figure below.
 
@@ -97,8 +97,8 @@ set large exodus file on
 export Genesis  "thincurr_ex-torus.g" overwrite block 1
 ```
 
-The file can then be converted to OFT's native mesh format using the `convert_cubit.py` script as
+The file can then be converted to OFT's native mesh format using the `OFT_convert_cubit.py` script as
 
-    python /path/to/OFT/bin/convert_cubit.py --in_file=thincurr_ex-torus.g
+    python /path/to/OFT/bin/OFT_convert_cubit.py --in_file=thincurr_ex-torus.g
 
 which will yield the converted file `thincurr_ex-torus.h5`.

src/docs/doc_mesh_native.md

@@ -28,22 +28,22 @@ As OFT only provides mesh generation capability for selected cases, most files w
 by one of the provided conversion scripts from software-specfic formats (eg. CUBIT, gmsh, etc.).
 
 \subsection doc_mesh_native_conv_cubit Converting CUBIT files
-To convert from CUBIT meshes saved using the Exodus/Gensis file format use the `convert_cubit.py` script
+To convert from CUBIT meshes saved using the Exodus/Gensis file format use the `OFT_convert_cubit.py` script
 (as below). The `--in_file` argument must be specified and by default a new file is created in native
 format with the same name, but `*.h5` extension, in the current working directory. Additional options
 to control inclusion of periodicity information are available (use `--help` for more information).
 
 \verbatim
-~$ python /path/to/oft/bin/convert_cubit.py --in_file=/path/to/cubit_mesh.g
+~$ python /path/to/oft/bin/OFT_convert_cubit.py --in_file=/path/to/cubit_mesh.g
 \endverbatim
 
 \subsection doc_mesh_native_conv_gmsh Converting Gmsh files
 To convert from Gmsh meshes saved using the [MSH file format](https://gmsh.info/doc/texinfo/gmsh.html#MSH-file-format)
-use the `convert_gmsh.py` script (as below). The `--in_file` argument must be specified and by default a new file is created in native
+use the `OFT_convert_gmsh.py` script (as below). The `--in_file` argument must be specified and by default a new file is created in native
 format with the same name, but `*.h5` extension, in the current working directory.
 
 \note Currently only Tet/Tri meshes are supported in both linear and quadratic variants.
 
 \verbatim
-~$ python /path/to/oft/bin/convert_gmsh.py --in_file=/path/to/gmsh_mesh.msh
+~$ python /path/to/oft/bin/OFT_convert_gmsh.py --in_file=/path/to/gmsh_mesh.msh
 \endverbatim

src/docs/doc_psitet_io.md

@@ -19,7 +19,7 @@ package. During a run subroutines are used to output the plotting mesh \ref oft_
 add time steps \ref oft_io::hdf5_create_timestep "hdf5_create_timestep", and output solution fields ex. \ref
 oft_io::hdf5_spdata "hdf5_spdata". Mesh and field information created during these calls are stored in <code>*.h5</code>
 files in the run directory along with a text file `dump.dat` which contains metadata describing the fields. After
-a run has completed the script `build_xdmf.py` can be used to build XML descriptor files which can be read by VisIt
+a run has completed the script `OFT_build_xdmf.py` can be used to build XML descriptor files which can be read by VisIt
 to produce visualization.
 
 \subsection doc_oft_io_plotting_representation Field Representation

src/examples/MUG/Spheromak_heating/MUG_sph_heat.F90

@@ -335,7 +335,7 @@ END PROGRAM MUG_sph_heat
 !!/
 !!\endverbatim
 !!
-!! Once the post-processing run is complete `bin/build_xdmf.py` can be used to generate `*.xmf` files that can be loaded by
+!! Once the post-processing run is complete `bin/OFT_build_xdmf.py` can be used to generate `*.xmf` files that can be loaded by
 !! [VisIt](https://visit-dav.github.io/visit-website/index.html), [ParaView](https://www.paraview.org/), or other visualization programs.
 !!
 !! \image html MUG_heat_ex-Fields.png "Resulting temperature distribution (shading) and magnetic field (vectors) at the end of the simulation, showing thermal confinement in the core of the torus."
@@ -362,18 +362,18 @@ END PROGRAM MUG_sph_heat
 !!mesh volume 1
 !!
 !!set duplicate block elements off
-!!block 1 add volume 1 
+!!block 1 add volume 1
 !!block 1 element type tetra10
 !!
 !!set large exodus file on
 !!export Genesis  "cyl_heat.g" overwrite block 1
 !!\endverbatim
 !!
-!! Once complete the mesh should be converted into the native mesh format using the `convert_cubit.py` script as
+!! Once complete the mesh should be converted into the native mesh format using the `OFT_convert_cubit.py` script as
 !! below. The script is located in `bin` following installation or `src/utilities` in the base repo.
 !!
 !!\verbatim
-!!~$ python convert_cubit.py --in_file=cyl_heat.g
+!!~$ python OFT_convert_cubit.py --in_file=cyl_heat.g
 !!\endverbatim
 !!
 !!\subsection doc_mug_sph_ex2_gmsh Meshing with Gmsh
@@ -406,9 +406,9 @@ END PROGRAM MUG_sph_heat
 !!~$ gmsh -3 -format mesh -optimize -clscale .2 -order 2 -o cyl_heat.mesh cyl_heat.geo
 !!\endverbatim
 !!
-!! Once complete the mesh should be converted into the native mesh format using the `convert_gmsh.py` script as
+!! Once complete the mesh should be converted into the native mesh format using the `OFT_convert_gmsh.py` script as
 !! below. The script is located in `bin` following installation or `src/utilities` in the base repo.
 !!
 !!\verbatim
-!!~$ python convert_gmsh.py --in_file=cyl_heat.mesh
+!!~$ python OFT_convert_gmsh.py --in_file=cyl_heat.mesh
 !!\endverbatim

src/examples/MUG/Spheromak_tilt/MUG_sph_tilt.F90

@@ -354,7 +354,7 @@ END PROGRAM MUG_sph_tilt
 !!/
 !!\endverbatim
 !!
-!! Once the post-processing run is complete `bin/build_xdmf.py` can be used to generate `*.xmf` files that can be loaded by
+!! Once the post-processing run is complete `bin/OFT_build_xdmf.py` can be used to generate `*.xmf` files that can be loaded by
 !! [VisIt](https://visit-dav.github.io/visit-website/index.html), [ParaView](https://www.paraview.org/), or other visualization programs.
 !!
 !! \image html MUG_tilt_ex-Fields.png "Magnetic field distribution of the initial (left) and final (right) states"
@@ -381,18 +381,18 @@ END PROGRAM MUG_sph_tilt
 !!mesh volume 1
 !!
 !!set duplicate block elements off
-!!block 1 add volume 1 
+!!block 1 add volume 1
 !!block 1 element type tetra10
 !!
 !!set large exodus file on
 !!export Genesis  "cyl_tilt.g" overwrite block 1
 !!\endverbatim
 !!
-!! Once complete the mesh should be converted into the native mesh format using the `convert_cubit.py` script as
+!! Once complete the mesh should be converted into the native mesh format using the `OFT_convert_cubit.py` script as
 !! below. The script is located in `bin` following installation or `src/utilities` in the base repo.
 !!
 !!\verbatim
-!!~$ python convert_cubit.py --in_file=cyl_tilt.g
+!!~$ python OFT_convert_cubit.py --in_file=cyl_tilt.g
 !!\endverbatim
 !!
 !!\subsection doc_mug_sph_ex1_gmsh Meshing with Gmsh
@@ -425,9 +425,9 @@ END PROGRAM MUG_sph_tilt
 !!~$ gmsh -3 -format mesh -optimize -clscale .2 -order 2 -o cyl_tilt.mesh cyl_tilt.geo
 !!\endverbatim
 !!
-!! Once complete the mesh should be converted into the native mesh format using the `convert_gmsh.py` script as
+!! Once complete the mesh should be converted into the native mesh format using the `OFT_convert_gmsh.py` script as
 !! below. The script is located in `bin` following installation or `src/utilities` in the base repo.
 !!
 !!\verbatim
-!!~$ python convert_gmsh.py --in_file=cyl_tilt.mesh
+!!~$ python OFT_convert_gmsh.py --in_file=cyl_tilt.mesh
 !!\endverbatim