Document tools; add tools for converting native sampler outputs

docs/sphinx/user/tools.rst

@@ -0,0 +1,116 @@
+.. spelling:word-list::
+
+   fcompare
+   csv
+
+.. _tools:
+
+Tools reference
+===============
+
+This section summarizes the functionality of the auxiliary tools included
+in the AMR-Wind ``tools/`` directory. There are two main parts of this folder. Python
+scripts, which do not require compilation, are in ``tools/``. C++ programs, which
+are compiled as separate executables when AMR-Wind is compiled, are saved in ``tools/utilities/``.
+After compilation, these executables can be found in the build directory, where each has its own 
+folder within ``tools/utilities/`` there.
+
+These capabilities are not meant to be exhaustive and are not maintained as actively as the
+solver source code. More tools for interacting with AMR-Wind data (pre- and post-processing)
+can be found in `amr-wind-frontend <https://github.com/Exawind/amr-wind-frontend>`_.
+
+Python scripts
+--------------
+
+.. input_param:: amrex_particle.py
+
+    Contains helpful routines for manipulating AMReX particle data.
+
+.. input_param:: amrex_plotfile.py
+
+    Contains helpful routines for manipulating AMReX plotfile data.
+
+.. input_param:: amrex_utils.py
+
+    Contains helpful routines for interacting with AMReX data structures.
+
+.. input_param:: calc_inflowoutflow_stats.py
+
+    Tool to process statistics from precursor ABL runs and provide information to populate certain inputs of a subsequent inflow-outflow simulation.
+
+.. input_param:: convert_amrex_hdf5_plotfile.py
+
+    Converts plotfiles written in HDF5 format to plain numpy data files.
+
+.. input_param:: convert_native_sample_to_time_series.py
+
+    Converts sampler data written in native format to a time series written in ASCII format. This is intended for scenarios when there is a single sampler point of interest, which has to be specified by naming the sampler labels and point index.
+
+.. input_param:: convert_native_sampling_to_structured_ascii.py
+
+    Converts sampler data written in native format to files written in ASCII format. For every sampling folder (i.e. every output step), this sampler creates a file for each sampler group, where each file lists the sampled data in order of the points belonging to that sampler.
+
+.. input_param:: example_plotfile_io.py
+
+    Example script for directly interacting with plotfile data.
+
+.. input_param:: fcompare_particles.py
+
+    Tool to compare native AMReX particle data. This has similar capability to the AMReX ``fcompare`` utility, which compares mesh data written to AMReX plotfiles.
+
+.. input_param:: generate_native_boundary_plane.py
+
+    Tool to generate arbitrary temporal and spatially varying boundary conditions via boundary plane files written in native format.
+
+.. input_param:: generate_native_boundary_plane_header.py
+
+    Tool to generate native format boundary plane header files for arbitrary temporal and spatially varying boundary conditions.
+
+.. input_param:: modify_hdf5_attributes.py
+
+    Modifies HDF5 attributes of files in order to be read into yt.
+
+.. input_param:: native_boundary_plane.py
+
+    Contains helpful routines for manipulating native boundary plane data.
+
+.. input_param:: refine_native_boundary_plane.py
+
+    Apply mesh refinement to a boundary plane file written in native format.
+
+.. input_param:: sampling_dam_break_godunov_ascii.py
+
+    Example script for plotting free surface sampler outputs in ASCII format.
+
+.. input_param:: sampling_dam_break_godunov_native.py
+
+    Example script for plotting free surface sampler outputs in native particle format.
+
+.. input_param:: sampling_dam_break_godunov_netcdf.py
+
+    Example script for plotting free surface sampler outputs in NetCDF format.
+
+
+C++ programs (utilities)
+------------------------
+
+
+.. input_param:: CheckpointToCSV
+
+    Converts checkpoint files to CSV format.
+
+.. input_param:: PlotfileToCSV
+
+    Converts checkpoint files to CSV format.
+
+.. input_param:: coarsen-chkpt
+
+    Reads in a checkpoint file and adds a coarser base level to the existing grid.
+
+.. input_param:: compareMultilevelToReference
+
+    Compares plotfiles (similar to fcompare) when the grid refinements do not exactly match between the two.
+
+.. input_param:: refine-chkpt
+
+    Reads in a checkpoint file and refines it by increasing its base resolution.

docs/sphinx/user/user.rst

@@ -14,3 +14,4 @@ User Manual
    faq.rst
    post_processing_examples.rst
    compression
+   tools.rst

tools/README.md

@@ -1,87 +1,7 @@
 # Preprocessing and postprocessing tools
 
 This directory contains a collection of helpful preprocessing and
-postprocessing utilities.
-
-## Preprocessing scripts
-
-### naluwind2amrwind.py
-The [naluwind2amrwind.py](naluwind2amrwind.py) python script allows you to
-convert a Nalu-wind input file to an amr-wind input file.  To the best of 
-its ability, it will try to take the parameters from Nalu-wind and map them 
-to amr-wind.
-
-The basic usage is given by:  
-```bash
-usage: naluwind2amrwind.py [-h] [--outfile OUTFILE] yamlfile
-
-Convert Nalu-Wind input file to AMR-wind input file
-
-positional arguments:
-  yamlfile
-
-optional arguments:
-  -h, --help         show this help message and exit
-  --outfile OUTFILE  write output to this file
-```
-
-For instance, to convert the Nalu-wind input file `naluwind.yaml`, run
-```bash
-$ ./naluwind2amrwind.py naluwind.yaml
-
-#---------------------------------------#
-#            SIMULATION STOP            #
-#---------------------------------------#
-time.stop_time                 = 20000.0                        # Max (simulated) time to evolve
-time.max_step                  = 40000                          # Max number of time steps
-
-#---------------------------------------#
-#         TIME STEP COMPUTATION         #
-#---------------------------------------#
-time.fixed_dt                  = 0.5                            # Use this constant dt if > 0
-time.cfl                       = 0.95                           # CFL factor
-
-#---------------------------------------#
-#            INPUT AND OUTPUT           #
-#---------------------------------------#
-time.plot_interval             = 1000                           # Steps between plot files
-time.checkpoint_interval       = 1000                           # Steps between checkpoint files
-
-[...snip...]
-```
-Use the `--outfile` option to write the output to a file instead.  Note 
-that the `nalu_abl_mesh` and `nalu_preprocess` section should be present 
-in the yaml file for it to correctly extract the geometry and the 
-inversion layer properties.
-
-## Postprocessing scripts
-
-### postproamrwind.py
-
-The [postproamrwind.py](postproamrwind.py) python provides a quick
-method to time-average and extract data from the `line_plot.txt`
-output.
-
-The major functions in this code are:
-- `loadfile(filename, t1, t2, headerinfo=[])`: Loads the line_plot.txt
-  file given by `filename`, for all times between `t1` and `t2`.
-- `timeaverage(dat, t1, t2, Ncells, Ncomp)`: Time averages the
-  line_plot data given by `dat`, between times `t1` and `t2`.
-- `avglineplot(filename, t1,t2, headerinfo=[])`: Combines `loadfile()`
-  and `timeaverage()`, so it loads the line_plot.txt given by
-  `filename`, and averages it between `t1` and `t2`.
-- `extractvars(dat, colheaders, varnames)`: Returns the variable(s)
-  matching the variables in varnames
-
-A short example of how to use the code is shown below.  In this case,
-we load the `line_plot.txt` file, average from 0 to 100 seconds, and
-plot the averaged U velocity versus z.
-
-```python
-import postproamrwind
-import matplotlib.pylot as plt
-avgdat, headers = postproamrwind.avglineplot('line_plot.txt',0,100)
-amrvars         = postproamrwind.extractvars(avgdat, headers, ['z','u_avg'])
-plt.plot(amrvars['u_avg'], amrvars['z'])
-plt.show()
-```
+postprocessing utilities. Please consult the documentation more information,
+including a brief summary of each one. The source code for tools written in C++ is
+in the utilities directory. These are compiled with AMR-Wind, and their executables
+are written to folders in the same build directory.