Merge pull request #6 from byuflowlab/dev

Dev

Project.toml

@@ -1,7 +1,7 @@
 name = "FLOWVPM"
 uuid = "6e19019d-7c31-4940-9d16-c3f15dfe6020"
 authors = ["Eduardo J. Alvarez <[email protected]>"]
-version = "3.0.0"
+version = "3.0.1"
 
 [deps]
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"

README.md

@@ -1,6 +1,8 @@
-<img src="docs/img/flowvpm2.jpg" alt="Pic here" style="width:700px"/>
-
-##### MESHLESS LARGE EDDY SIMULATION THROUGH THE REFORMULATED VORTEX PARTICLE METHOD
+<p align="center">
+  <img src="docs/img/flowvpm2.jpg" alt="Pic here" style="width:75%"/>
+  <br>
+  <i><b>Meshless large eddy simulation through the reformulated vortex particle method</b></i>
+</p>
 
 ---
 
@@ -26,7 +28,7 @@ Limited support is provided for MacOs and Windows machines, and we would graciou
 
 ## Features
   * Fast-multipole acceleration through [ExaFMM](https://github.com/byuflowlab/FLOWExaFMM)
-  * Threaded CPU parallelization through OpenMPI
+  * Threaded CPU parallelization through OpenMP
   * Meshless
   * Second-order spatial accuracy and third-order RK time integration
   * Numerically stable by reshaping particles subject to vortex stretching

examples/utilities/utilities.jl

@@ -1,17 +1,15 @@
 #=##############################################################################
 # DESCRIPTION
-    Utilitiesand examples for processing VPM simulations.
+    Utilities and examples for processing VPM simulations.
 
 # AUTHORSHIP
   * Author    : Eduardo J. Alvarez
   * Email     : [email protected]
   * Created   : Oct 2021
-  * Copyright : Eduardo J. Alvarez. All rights reserved.
 =###############################################################################
 
 import Printf: @printf
 
-# https://github.com/byuflowlab/GeometricTools.jl
 import GeometricTools as gt
 
 import FLOWVPM as vpm

examples/utilities/utilities_fluiddomain.jl

@@ -7,63 +7,62 @@
   * Author    : Eduardo J. Alvarez
   * Email     : [email protected]
   * Created   : Oct 2021
-  * Copyright : Eduardo J. Alvarez. All rights reserved.
 =###############################################################################
 
 
 """
-    `evaluate_fluiddomain_vtk(pfield::FLOWVPM.ParticleField,
-grids::Array{<:GeometricTools.AbstractGrid}; optargs...)`
+    computefluiddomain( pfield::FLOWVPM.ParticleField,
+                        grids::Array{<:GeometricTools.AbstractGrid};
+                        optargs...
+                        )
 
-    Evaluate the velocity and vorticity field induced by the particle field
+Evaluate the velocity and vorticity field induced by the particle field
 `pfield` at all nodes in a set of grids `grids`. The fields are added as
 solution fields `U` and `W` in each grid. The analytic Jacobian of the velocity
-field can also be added with the optional argument `add_J=true`.
+field can also be saved using the optional argument `add_J=true`.
 
 
 # OPTIONAL ARGUMENTS
 
 ## Processing options
-* `add_J::Bool`             : Add the solution fields `J1`, `J2`, and `J3` to
+* `add_J::Bool=false`       : Add the solution fields `J1`, `J2`, and `J3` to
                                 each grid, where Ji[j]=dUi/dxj.
-* `add_Uinf::Bool`          : It evaluates and adds a uniform freestream to the
-                                `U` field.
-* `add_Wapprox::Bool`       : It evaluates and adds the RBF-approximated
-                                vorticity field.
-* `zeta::Function`          : Method for evaluating RBF-approximated vorticity
+* `add_Uinf::Bool=false`    : It evaluates and adds the uniform freestream to
+                                the `U` field.
+* `add_Wapprox::Bool=false` : It evaluates and saves the RBF-approximated
+                                vorticity field under the field `Wapprox`.
+* `zeta::Function=FLOWVPM.zeta_fmm` : Method for evaluating RBF-approximated vorticity
                                 (used only if `add_Wapprox==true`).
-* `scale_sigma::Real`       : It rescales the smoothing radius of each particle
+* `scale_sigma::Real=1.0`   : It rescales the smoothing radius of each particle
                                 by this factor before evaluating the particle
                                 field.
-* `f_Gamma::Real`           : Factor used to add the nodes as particles.
-* `f_sigma::Real`           : Factor used to add the nodes as particles.
 
 ## Output options
-* `save_path::String`       : If used, it will save the grids as VTK files under
-                                this path.
-* `file_pref::String`       : Prefix for VTK files.
-* `grid_names::String`      : Name of each grid for VTK file. If not given, it
+* `save_path::String`       : If used, it will save the grids as XDMF files
+                                under this path.
+* `file_pref::String`       : Prefix for XDMF files.
+* `grid_names::String`      : Name of each grid for XDMF files. If not given, it
                                 will generate their names automatically.
-* `num::Int`                : If given, the name of the VTK file will be
+* `num::Int`                : If given, the name of the XDMF files will be
                                 `"\$(file_pref)\$(grid_names[i]).\$(num).vtk"`
-* `verbose::Bool`           : Activate/deactivate verbose.
+* `verbose::Bool=true`      : Activate/deactivate verbose.
+* `v_lvl::Int=0`            : Indentation level for printing verbose.
 
 
-NOTE: The solution fields `U`, `W`, and Jacobian do not include the freestream
+**NOTE:** The solution fields `U`, `W`, and Jacobian do not include the freestream
         field, but rather they only include the fields induced by the particles.
-        To add the freestream to the `U`, use the optional argument
-        `add_Uinf=true`.
+        To add the freestream to `U`, use the optional argument `add_Uinf=true`.
 """
-function evaluate_fluiddomain_vtk(pfield::vpm.ParticleField,
+function computefluiddomain(pfield::vpm.ParticleField,
                                     grids::Array{<:gt.AbstractGrid};
                                     # PROCESSING OPTIONS
                                     add_J=false,
                                     add_Uinf=false,
                                     add_Wapprox=false,
                                     zeta=vpm.zeta_fmm,
                                     scale_sigma=1.0,
-                                    f_Gamma=1e-2,
-                                    f_sigma=0.5,
+                                    f_Gamma=1e-2,   # Factor used to add the nodes as particles
+                                    f_sigma=0.5,    # Factor used to add the nodes as particles
                                     remove_nodeparticles=true,
                                     # OUTPUT OPTIONS
                                     save_path=nothing,
@@ -221,12 +220,19 @@ end
 
 
 """
-    `evaluate_fluiddomain_vtk(pfield::vpm.ParticleField, nums,
-read_path::String, file_pref::String, grids; origin=nothing,
-orientation=nothing, optargs...)`
-
-    Evaluate the fluid domain induced by all the time steps `nums` found in
-a particle field simulation saved under `read_path`. `file_pref` indicates the
+    computefluiddomain(pfield::vpm.ParticleField,
+                        nums::Vector{Int}, read_path::String, file_pref::String,
+                        grids;
+                        origin=nothing,
+                        orientation=nothing,
+                        other_read_paths=[],
+                        other_file_prefs=[],
+                        userfunction_pfield=(pfield, num, grids)->nothing,
+                        optargs...
+                        )
+
+Evaluate the fluid domain at each time step in `nums` that is induced by
+a particle field saved under `read_path`. `file_pref` indicates the
 prefix of the .h5 files to read.
 
 To translate and re-orient the grids at each time step, the user can pass the
@@ -239,8 +245,16 @@ user must make sure that sufficient memory has been preallocated to hold
 the number of particles of each time step that will be read, plus the number
 of nodes in the grids. The fluid domain will be evaluated using the UJ and FMM
 configuration of the given `pfield` particle field.
+
+To read and add more than one particle field at each time step, pass a list
+of paths and prefixes through `other_read_paths` and `other_file_prefs`. This
+is useful for reading and incluiding a set of static particles, for example.
+
+Give it a function `userfunction_pfield` to pre-process the resulting particle
+field before evaluating the fluid domain (*e.g.*, remove particles, resize core
+sizes, etc).
 """
-function evaluate_fluiddomain_vtk(pfield::vpm.ParticleField,
+function computefluiddomain(pfield::vpm.ParticleField,
                                     nums, read_path::String, file_pref::String,
                                     grids;
                                     origin=nothing,
@@ -310,7 +324,7 @@ function evaluate_fluiddomain_vtk(pfield::vpm.ParticleField,
         userfunction_pfield(pfield, num, grids)
 
         # Proceed to evaluate the particle field on the nodes of each grid
-        evaluate_fluiddomain_vtk(pfield, grids;
+        computefluiddomain(pfield, grids;
                                     remove_nodeparticles=false,
                                      verbose=verbose, v_lvl=v_lvl+1, num=num,
                                      optargs...)
@@ -320,15 +334,21 @@ function evaluate_fluiddomain_vtk(pfield::vpm.ParticleField,
 end
 
 """
-    `evaluate_fluiddomain_vtk(maxparticles::Int, args...; UJ::Function=vpm.UJ_fmm,
-fmm::FLOWVPM.FMM=vpm.FMM(; p=4, ncrit=50, theta=0.4, phi=0.5), optargs...)`
-
-    Just like the other `evaluate_fluiddomain_vtk(args...; optargs...)` methods
-but automatically pre-allocating and initializing the particle field with the
+    computefluiddomain(maxparticles::Int, args...;
+                        UJ::Function=vpm.UJ_fmm,
+                        fmm::FLOWVPM.FMM=vpm.FMM(; p=4, ncrit=50, theta=0.4, phi=0.5),
+                        pfield_optargs=[]
+                        optargs...)
+
+Like the other `computefluiddomain(args...; optargs...)` methods, but
+automatically pre-allocating and initializing the particle field with the
 given maximum number of particles, UJ evaluation method, and FMM configuration
 (if FMM is used by UJ).
+
+Use `pfield_optargs` to pass any additional optional arguments to the particle
+field constructor.
 """
-function evaluate_fluiddomain_vtk(maxparticles::Int, args...;
+function computefluiddomain(maxparticles::Int, args...;
                                     UJ=vpm.UJ_fmm,
                                     fmm=vpm.FMM(; p=4, ncrit=50, theta=0.4, phi=0.5),
                                     pfield_optargs=[],
@@ -342,36 +362,39 @@ function evaluate_fluiddomain_vtk(maxparticles::Int, args...;
     # Pre-allocate memory
     pfield = vpm.ParticleField(maxparticles; UJ=UJ, fmm=fmm, pfield_optargs...)
 
-    return evaluate_fluiddomain_vtk(pfield, args...;
+    return computefluiddomain(pfield, args...;
                                       verbose=verbose, v_lvl=v_lvl, optargs...)
 end
 
 
 
 """
-    `evaluate_fluiddomain_vtk(P_min, P_max, NDIVS, args...;
-spacetransform=nothing, O=zeros(3), Oaxis=Float64[i==j for i in 1:3, j in 1:3],
-optargs...)`
+    computefluiddomain(P_min, P_max, NDIVS, args...;
+                        spacetransform=nothing,
+                        O=zeros(3), Oaxis=Float64[i==j for i in 1:3, j in 1:3],
+                        optargs...)`
 
-    Just like the other `evaluate_fluiddomain_vtk(args...; optargs...)` methods
+Like the other `computefluiddomain(args...; optargs...)` methods,
 but automatically generating a fluid domain grid. The grid is generated as a
 Cartesian box with minimum and maximum corners `P_min` and `P_max` and `NDIVS`
 cells.
 
-For instance, `P_min=[-1, -1, -1], P_max=[-1, -1, -1], NDIVS=[10, 10, 50]`
-will grid the volumetric space between -1 and 1 in all directions, with 10
-cells in both the x and y-direction, and 50 cells in the z-direction.
+For instance, `P_min=[-1, -1, -1]`, `P_max=[-1, -1, -1]`, and
+`NDIVS=[10, 10, 50]` will grid the volumetric space between -1 and 1 in all
+directions, with 10 cells in both the x and y-direction, and 50 cells in the
+z-direction.
 
 Even though the grid is first generated as a Cartesian grid, this can be
 transformed into any other structured space through the argument
-`spacetransform` which is intended to receive a function that takes any vector
-and returns another vector of the same dimension. For instance,
+`spacetransform`, which is a function that takes any vector
+and returns another vector of the same dimensions. For instance,
 `P_min=[0.5, 0, 0], P_max=[1, 2*pi, 5], NDIVS=[10, 20, 30],
 spacetransform=GeometricTools.cylindrical3D` will generate a cylindrical grid
-discretizing the radial annulus from 0.5 to 1 with 10 cells, angle from 0 to
-360deg with 20 cells, and axial z-distance from 0 through 5 with 30 cells.
+discretizing the radial annulus from 0.5 to 1 with 10 cells, the polar angle
+from 0 to 360deg with 20 cells, and the axial z-distance from 0 through 5 with
+30 cells.
 
-Any number of dimensions can be given, just make sure that `P_min`,
+Any number of dimensions can be used, but make sure that `P_min`,
 `P_max`, and `NDIVS` always have three dimensions and indicate the dimensions
 that are "collapsed" with a 0 in `NDIVS`. Even though the grid is defined in
 the Cartesian axes, the origin and orientation of the grid can be specified
@@ -381,21 +404,21 @@ will generate a 2D surface laying in the xy-plane at z=1.0, spanning from
 (x,y)=(0,0) to (x,y)=(2,3.5). Use `O=[0, 0, -1]` to move the surface back to the
 xy-plane at z=0. Use `Oaxis=[1 0 0; 0 0 -1; 0 1 0]` to re-orient the
 surface to lay in the zx-plane. The same thing can be achieved with
-`Oaxis=gt.rotation_matrix2(-90, 0, 0)` which generates the rotation matrix
-corresponding to a -90deg rotation about the x-axis.
+`Oaxis=GeometricTools.rotation_matrix2(-90, 0, 0)` which generates the rotation
+matrix corresponding to a -90deg rotation about the x-axis.
 
-NOTE: The order of operation goes from (1) Cartesian grid generation, (2) space
+**NOTE:** The order of operation is (1) Cartesian grid generation, (2) space
 transformation if any, and (3) translation and re-orientation to the given
 origin and orientation.
 """
-function evaluate_fluiddomain_vtk(P_min, P_max, NDIVS, args...;
+function computefluiddomain(P_min, P_max, NDIVS, args...;
                                     spacetransform=nothing,
                                     O=zeros(3),
                                     Oaxis=Float64[i==j for i in 1:3, j in 1:3],
                                     grid_optargs=[],
                                     verbose=true, v_lvl=0,
                                     debug=false, save_path=nothing,
-                                    optargs...) where {T}
+                                    optargs...)
 
     if verbose
         println("\t"^(v_lvl)*"Generating fluid domain grid...")
@@ -426,9 +449,12 @@ function evaluate_fluiddomain_vtk(P_min, P_max, NDIVS, args...;
     end
 
     # Proceed to evaluate the fluid domain on this grid
-    out = evaluate_fluiddomain_vtk(args..., [grid];
+    out = computefluiddomain(args..., [grid];
                                       save_path=save_path,
                                       verbose=verbose, v_lvl=v_lvl, optargs...)
 
     return out, grid
 end
+
+# Deprecated name
+evaluate_fluiddomain_vtk = computefluiddomain

src/FLOWVPM.jl

@@ -30,6 +30,9 @@ const fmm = FLOWExaFMM
 
 # ------------ GLOBAL VARIABLES ------------------------------------------------
 const module_path = splitdir(@__FILE__)[1]      # Path to this module
+const examples_path  = joinpath(module_path, "..", "examples") # Path to examples
+const utilities_path = joinpath(examples_path, "utilities") # Path to utilities
+const utilities = joinpath(examples_path, "utilities", "utilities.jl") # Utilities
 
 # Determine the floating point precision of ExaFMM
 const exafmm_single_precision = fmm.getPrecision()