utilities for the flowVC project
Tip
Check out the Docs
Clone and install the repository
git clone https://github.com/bkm82/flowVC-utils.git
cd flowVC-utilsInstall the package (optional add a -e after install for editable mode)
pip install .Usage: python -m flowvcutils [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
Commands:
filerename Rename the files in a directory
filerenumber Renumber the files in a directory
inigenerator Generate a .ini file for the flow vc.
jsonlogger Print a specified number of log lines.
simulationgenerator Generate the simulation directorys.
Convert a file file from a vtu file format to a .bin file that can be read and utilized by the flowVC code
For more information, refer to https://shaddenlab.berkeley.edu/uploads/releasenotes.pdf
cd dir
python -m flowvcutils.vtu_2_bin start stopusage: vtu_2_bin.py [-h] [--process {folder,directory}] [--root ROOT]
[--output OUTPUT] [--file_name FILE_NAME]
[--extension EXTENSION] [--increment INCREMENT]
[--num_digits NUM_DIGITS] [--field_name FIELD_NAME]
start stop
Process VTU files to a .bin format.
positional arguments:
start Starting index for the processing files (required).
stop Stopping index for the processing files (required).
options:
-h, --help show this help message and exit
--process {folder,directory}
Processing mode: 'folder' for a single folder or
'directory'to process subdirectories (default:
'folder').
--root ROOT Input directory with the VTU files (default: current
directory).
--output OUTPUT Output directory (default: current directory).
--file_name FILE_NAME
Base file name (e.g., steady_ for
steady_00000.vtu)(default= directory name).
--extension EXTENSION
File extension (default: '.vtu').
--increment INCREMENT
Increment between each vtu file (default = 50).
--num_digits NUM_DIGITS
Digits in file name (e.g., 5 for test_00100.vtu).
(default: 5).
--field_name FIELD_NAME
Field name for velocity data (default: 'velocity').
filename_cordinates.bin will have a file format in the following form
n x_0 y_0 z_0 x_1 y_1 z_1 ... x_(n-1) y_(n-1) z_(n-1)
where
n(int): the number of components
x(double): the x cordianate of the point
y(double): the y cordianate of the point
z(double): the z cordianate of the point
filename_connectivity.bin will have a file format
e i_0^0 i_0^1 i_0^2 i_0^3 i_1^0 i_1^1 i_1^2 i_0^3 ....
where
e(int): the number of elements
i_0:(4 ints) the 4 elements that make up an element
filename_adjacency.bin will have a file format
e e_0^0 e_0^1 e_0^2 e_0^3 e_1^0 e_1^1 e_1^2 e_0^3 ....
where
e(int): the number of elements
i_0:(4 ints) the 4 elements that share a common face with the element
The inigenerator utility is utilized to create the flowVC input files for multiple simulations. The utility reads a configuration file wich can be used to set default paramaters (config.inigenerator.cfg) and adjusts input/output paths for each case.The utility can also be used to determines 3D coordinate bounds, streaching them slighly to meet the flowVC requirement of having cubic cells. Essentially the utility helps manage
- Directory paths (where input data is stored, where outputs go, etc.)
- Mesh bounds for the data (e.g., xmin, xmax, ymin, ymax, zmin, zmax).
- Resolution in each dimension (xres, yres, zres) based on the cell size.
- Time direction settings (forward or backward) for the FTLE-related output.
- Name prefixes and other run-time details that go into the final configuration so the output FTLE files are identifiable for each simulation case.
To view the help menu run:
python -m flowvcutils inigenerator --helpThe defaults for the .in settings can be found and changed in the flowVC_utils/src/config directory. The tool assumes that the results of the simulation are organized in the following folder structure, where “project_root” and “case1” can be any name, but the “input_bin” “input_vtu” and “output_bin” directory names are exactly as shown:
project_root
└── case1
├── input_bin
├── input_vtu
└── output_bin
Optional flags include -d, –directory: This specifies where to run the tool from, with a default being the current directory you are in.
–autorange: This flag can be utilized to have the tool read the mesh bounds for the DataMesh and FTLEMesh from the simulation results data. To use this flag ensure there is at least one .vtu file in the input_vtu directory. If it is not set whatever is in the configuration file will be utilized.
–cell_size: The cell size for the FTLE mesh with a default of 0.001
–manual_bounds: This can be utilized to set the min_x, min_y, min_z, max_x, max_y, and max_z for the FTLE mesh. This is useful when attempting to compute the ftle field on a smaller subset (i.e. slice) of the result domain.
–direction: This can be utilized to specify the computation of an attracting (backward) or repeling (forward) FTLE field.
–batch: This creates input files for multiple simulation result cases at once. To utilize this ensure your project is organized as follows
-project_directory
project_root
├── case1
│ ├── input_bin
│ ├── input_vtu
│ └── output_bin
└── case2
├── input_bin
├── input_vtu
└── output_bin
To generate the FTLE mesh over the entire computation domain for multiple simulation results you can run:
python -m flowvcutils inigenerator --auto_range True --batchTo generate an FTLE field for a slice of the domain at a higher resolution you can run:
python -m flowvcutils inigenerator -cell_size 0.0001 --auto_range True --manual_bounds -0.000976751 0.145677 0.12361 -0.00095 0.203633 0.236885 --batchIt is not critical that the range is perfectly divisible by the cell_size, the tool will increase the mesh bounds max slightly ensuring the cell size remains constant. However notice how in this case the x_min and x_max are far enough apart to generate at least 2 cells in the x-direction. This creates a pseudo-2D ftle mesh slice out of the domain, as the flowVC tool requires 2 cells every direction when a 3D mesh is utilized.
Rename the files in a directory. For example From:
dir
├── all_results_00000.vtu
├── all_results_00050.vtu
├── all_results_00100.vtu
To
dir
├── directory_name_00000.vtu
├── directory_name_00050.vtu
├── directory_name_00100.vtu
Usage: python -m flowvcutils filerename [OPTIONS]
Rename the files in a directory
Example
Take the files in a directory
-------
directory
├── all_results_00000.vtu
├── all_results_00050.vtu
├── all_results_00100.vtu
and renames them to
directory
├── directory_00000.vtu
├── directory_00050.vtu
├── directory_00100.vtu
Options:
-d, --directory TEXT Directory to run program (default: current dir)
--prefix TEXT New file name (default:current directory name).
--current_name TEXT Current file name (default:all_results).
-h, --help Show this message and exit.
Renumber the files in a directory. For example From:
dir
├── file_name.0.vtk
├── file_name.1.vtk
├── ...
├── file_name.39.vtk
To
dir
├── file_name.3050.vtk
├── file_name.3100.vtk
├── ...
├── file_name.5000.vtk
Usage: python -m flowvcutils filerenumber [OPTIONS]
Renumber the files in a directory
Example
python -m flowvcutils filerenumber
takes a directory with files file_name.0.vtk file_name.1.vtk ...
file_name.39.vtk
and renames them to
file_name.3000.vtk file_name.3050.vtk ... file_name.5000.vtk
Options:
-d, --directory TEXT Directory to run program (default: current dir)
--prefix TEXT new file name (default:current directory name).
--current_start INTEGER Current file number start.
--current_end INTEGER Current file number start.
--new_start INTEGER Current file number start.
--increment INTEGER Current file number start.
-h, --help Show this message and exit.
On Monsoon, NAU’s computer cluster, the flowVC-utils can be installed into a conda enviroment.
First the mamaforge module is loaded using the following command
module load mambaforge
conda env listOnce conda is loaded, a new anaconda enviroment can be created and activated.
conda env create flowvcutils
conda activate flowvcutilsOnce inside a conda enviroment, the flowVC-utils project can be cloned from the github source code located https://github.com/bkm82/flowVC-utils. It is installed via editable mode.
git clone https://github.com/bkm82/flowVC-utils.git
cd flowVC-utils
pip install -e .Installing it in editable (-e) mode allows for changes to the source code if needed without needing to reinstall. To update the code to the latest version on github run.
git checkout main
git pull