Skip to content

Commit 4f76d51

Browse files
mbkuhnmbkuhn
authored
Document tools; add tools for converting native sampler outputs (#1670)
* tool to convert native sampling to structured ascii output. one text file per sampler per directory. * tool to convert single particle from native to ascii time series * upgrade one of the scripts - much better parsing * same for the other script * adding some aborts for bad names * correcting description * small tweaks, including checking against sampler index in file * improve print statements and add fixed length (number of digits) input * document tools briefly * spelling list * deprecate old tools * add reference to frontend
1 parent f84ed57 commit 4f76d51

10 files changed

+422
-1009
lines changed

‎docs/sphinx/user/tools.rst‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. spelling:word-list::
2+
3+
fcompare
4+
csv
5+
6+
.. _tools:
7+
8+
Tools reference
9+
===============
10+
11+
This section summarizes the functionality of the auxiliary tools included
12+
in the AMR-Wind ``tools/`` directory. There are two main parts of this folder. Python
13+
scripts, which do not require compilation, are in ``tools/``. C++ programs, which
14+
are compiled as separate executables when AMR-Wind is compiled, are saved in ``tools/utilities/``.
15+
After compilation, these executables can be found in the build directory, where each has its own
16+
folder within ``tools/utilities/`` there.
17+
18+
These capabilities are not meant to be exhaustive and are not maintained as actively as the
19+
solver source code. More tools for interacting with AMR-Wind data (pre- and post-processing)
20+
can be found in `amr-wind-frontend <https://github.com/Exawind/amr-wind-frontend>`_.
21+
22+
Python scripts
23+
--------------
24+
25+
.. input_param:: amrex_particle.py
26+
27+
Contains helpful routines for manipulating AMReX particle data.
28+
29+
.. input_param:: amrex_plotfile.py
30+
31+
Contains helpful routines for manipulating AMReX plotfile data.
32+
33+
.. input_param:: amrex_utils.py
34+
35+
Contains helpful routines for interacting with AMReX data structures.
36+
37+
.. input_param:: calc_inflowoutflow_stats.py
38+
39+
Tool to process statistics from precursor ABL runs and provide information to populate certain inputs of a subsequent inflow-outflow simulation.
40+
41+
.. input_param:: convert_amrex_hdf5_plotfile.py
42+
43+
Converts plotfiles written in HDF5 format to plain numpy data files.
44+
45+
.. input_param:: convert_native_sample_to_time_series.py
46+
47+
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.
48+
49+
.. input_param:: convert_native_sampling_to_structured_ascii.py
50+
51+
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.
52+
53+
.. input_param:: example_plotfile_io.py
54+
55+
Example script for directly interacting with plotfile data.
56+
57+
.. input_param:: fcompare_particles.py
58+
59+
Tool to compare native AMReX particle data. This has similar capability to the AMReX ``fcompare`` utility, which compares mesh data written to AMReX plotfiles.
60+
61+
.. input_param:: generate_native_boundary_plane.py
62+
63+
Tool to generate arbitrary temporal and spatially varying boundary conditions via boundary plane files written in native format.
64+
65+
.. input_param:: generate_native_boundary_plane_header.py
66+
67+
Tool to generate native format boundary plane header files for arbitrary temporal and spatially varying boundary conditions.
68+
69+
.. input_param:: modify_hdf5_attributes.py
70+
71+
Modifies HDF5 attributes of files in order to be read into yt.
72+
73+
.. input_param:: native_boundary_plane.py
74+
75+
Contains helpful routines for manipulating native boundary plane data.
76+
77+
.. input_param:: refine_native_boundary_plane.py
78+
79+
Apply mesh refinement to a boundary plane file written in native format.
80+
81+
.. input_param:: sampling_dam_break_godunov_ascii.py
82+
83+
Example script for plotting free surface sampler outputs in ASCII format.
84+
85+
.. input_param:: sampling_dam_break_godunov_native.py
86+
87+
Example script for plotting free surface sampler outputs in native particle format.
88+
89+
.. input_param:: sampling_dam_break_godunov_netcdf.py
90+
91+
Example script for plotting free surface sampler outputs in NetCDF format.
92+
93+
94+
C++ programs (utilities)
95+
------------------------
96+
97+
98+
.. input_param:: CheckpointToCSV
99+
100+
Converts checkpoint files to CSV format.
101+
102+
.. input_param:: PlotfileToCSV
103+
104+
Converts checkpoint files to CSV format.
105+
106+
.. input_param:: coarsen-chkpt
107+
108+
Reads in a checkpoint file and adds a coarser base level to the existing grid.
109+
110+
.. input_param:: compareMultilevelToReference
111+
112+
Compares plotfiles (similar to fcompare) when the grid refinements do not exactly match between the two.
113+
114+
.. input_param:: refine-chkpt
115+
116+
Reads in a checkpoint file and refines it by increasing its base resolution.

‎docs/sphinx/user/user.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ User Manual
1414
faq.rst
1515
post_processing_examples.rst
1616
compression
17+
tools.rst

‎tools/README.md‎

Lines changed: 4 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,7 @@
11
# Preprocessing and postprocessing tools
22

33
This directory contains a collection of helpful preprocessing and
4-
postprocessing utilities.
5-
6-
## Preprocessing scripts
7-
8-
### naluwind2amrwind.py
9-
The [naluwind2amrwind.py](naluwind2amrwind.py) python script allows you to
10-
convert a Nalu-wind input file to an amr-wind input file. To the best of
11-
its ability, it will try to take the parameters from Nalu-wind and map them
12-
to amr-wind.
13-
14-
The basic usage is given by:
15-
```bash
16-
usage: naluwind2amrwind.py [-h] [--outfile OUTFILE] yamlfile
17-
18-
Convert Nalu-Wind input file to AMR-wind input file
19-
20-
positional arguments:
21-
yamlfile
22-
23-
optional arguments:
24-
-h, --help show this help message and exit
25-
--outfile OUTFILE write output to this file
26-
```
27-
28-
For instance, to convert the Nalu-wind input file `naluwind.yaml`, run
29-
```bash
30-
$ ./naluwind2amrwind.py naluwind.yaml
31-
32-
#---------------------------------------#
33-
# SIMULATION STOP #
34-
#---------------------------------------#
35-
time.stop_time = 20000.0 # Max (simulated) time to evolve
36-
time.max_step = 40000 # Max number of time steps
37-
38-
#---------------------------------------#
39-
# TIME STEP COMPUTATION #
40-
#---------------------------------------#
41-
time.fixed_dt = 0.5 # Use this constant dt if > 0
42-
time.cfl = 0.95 # CFL factor
43-
44-
#---------------------------------------#
45-
# INPUT AND OUTPUT #
46-
#---------------------------------------#
47-
time.plot_interval = 1000 # Steps between plot files
48-
time.checkpoint_interval = 1000 # Steps between checkpoint files
49-
50-
[...snip...]
51-
```
52-
Use the `--outfile` option to write the output to a file instead. Note
53-
that the `nalu_abl_mesh` and `nalu_preprocess` section should be present
54-
in the yaml file for it to correctly extract the geometry and the
55-
inversion layer properties.
56-
57-
## Postprocessing scripts
58-
59-
### postproamrwind.py
60-
61-
The [postproamrwind.py](postproamrwind.py) python provides a quick
62-
method to time-average and extract data from the `line_plot.txt`
63-
output.
64-
65-
The major functions in this code are:
66-
- `loadfile(filename, t1, t2, headerinfo=[])`: Loads the line_plot.txt
67-
file given by `filename`, for all times between `t1` and `t2`.
68-
- `timeaverage(dat, t1, t2, Ncells, Ncomp)`: Time averages the
69-
line_plot data given by `dat`, between times `t1` and `t2`.
70-
- `avglineplot(filename, t1,t2, headerinfo=[])`: Combines `loadfile()`
71-
and `timeaverage()`, so it loads the line_plot.txt given by
72-
`filename`, and averages it between `t1` and `t2`.
73-
- `extractvars(dat, colheaders, varnames)`: Returns the variable(s)
74-
matching the variables in varnames
75-
76-
A short example of how to use the code is shown below. In this case,
77-
we load the `line_plot.txt` file, average from 0 to 100 seconds, and
78-
plot the averaged U velocity versus z.
79-
80-
```python
81-
import postproamrwind
82-
import matplotlib.pylot as plt
83-
avgdat, headers = postproamrwind.avglineplot('line_plot.txt',0,100)
84-
amrvars = postproamrwind.extractvars(avgdat, headers, ['z','u_avg'])
85-
plt.plot(amrvars['u_avg'], amrvars['z'])
86-
plt.show()
87-
```
4+
postprocessing utilities. Please consult the documentation more information,
5+
including a brief summary of each one. The source code for tools written in C++ is
6+
in the utilities directory. These are compiled with AMR-Wind, and their executables
7+
are written to folders in the same build directory.

0 commit comments

Comments
 (0)