diff --git a/README.md b/README.md index 97de9c6..f3fedc6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ -\file README.md +``` +\file README.md \author Paul Ullrich \version May 8, 2024 +``` Copyright 2024 Paul Ullrich @@ -10,149 +12,220 @@ source code and its documentation under the terms of the GNU General Public License. This software is provided "as is" without express or implied warranty. -Spherical Quadrilateral Mesh Generator (SQuadGen) -================================================= +# Spherical Quadrilateral Mesh Generator (SQuadGen) -REQUIRED EXTERNAL LIBRARIES - libpng - libnetcdf +## REQUIRED EXTERNAL LIBRARIES -BUILDING - Modify src/Makefile to specify NetCDF paths - make all +libnetcdf -SYNOPSIS +## BUILDING + +Modify `src/Makefile` to specify NetCDF paths + +```sh +make all +``` + +## INSTALLING FROM CONDA PACKAGE + +An alternative to building SQuadGen from source is to install a pre-built Linux +verison from a conda package. + +If you don't already have a conda base environment set up, you can install +[miniforge3](https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge3). + +To add SQuadGen to an existing conda environment, activate the environment and +run: +```sh +conda install squadgen +``` + +To create a new conda environment with SQuadGen in it (and any other packages +you like, run: +```sh +conda create -n squadgen +``` +Then, activate the environment with: +```sh +conda activate +``` +The `SQuadGen` executable will be in your path. + +## SYNOPSIS +```sh ./SQuadGen +``` + +## PARAMETERS -PARAMETERS +``` --grid_type ["CS"] (Options: CS | ICO | OCT1 | OCT2) --refine_type ["LOWCONN"] (Options: LOWCONN | CUBIT | LOWCONNOLD) - --refine_level [2] - --resolution [10] - --refine_file [""] - --refine_rect [""] - --output [""] - --loadcsrefinementmap [false] + --refine_level [2] + --resolution [10] + --refine_file [""] + --refine_rect [""] + --output [""] + --loadcsrefinementmap [false] --smooth_type ["NONE"] (Options: NONE | SPRING | PRESSURE) --smooth_dist [1] (Smooth distance, -1 = smooth entire mesh) - --smooth_iter [10] - --lon_base [-180.000000] - --lat_base [0.000000] - --x_rotate [0.000000] - --y_rotate [0.000000] - --lon_ref [0.000000] - --lat_ref [0.000000] - --orient_ref [0.000000] - --tessellate [0] - --subcellres [0] - --invert [false] - --block_refine [false] - - -DESCRIPTION - SQuadGen is a mesh generation utility that uses a cubed-sphere base mesh to + --smooth_iter [10] + --lon_base [-180.000000] + --lat_base [0.000000] + --x_rotate [0.000000] + --y_rotate [0.000000] + --lon_ref [0.000000] + --lat_ref [0.000000] + --orient_ref [0.000000] + --tessellate [0] + --subcellres [0] + --invert [false] + --block_refine [false] +``` + +## DESCRIPTION + + `SQuadGen` is a mesh generation utility that uses a cubed-sphere base mesh to generate quadrilateral meshes with user-specified enhancements. In order to determine where enhancement is desired, the user provides a PNG file which corresponds to a latitude-longitude grid. Raster values with higher brightness (whiter values) are tagged for refinement. The algorithm uses a basic paving - technique and supports two paving stencil types: Low-connectivity (LOWCONN) - and CUBIT-type transition regions. + technique and supports two paving stencil types: Low-connectivity (`LOWCONN`) + and `CUBIT`-type transition regions. + +## OPTIONS + +`--grid_type (CS) | ICO` +
+ + Type of base mesh to use for refinement: cubed-sphere (`CS`) or icosahedral + (`ICO`). If `ICO` is specified, generate a basic icosahedral flag mesh. All + refinement criteria will be ignored in this case. +
+ +`--refine_type (LOWCONN) | CUBIT | LOWCONNOLD` +
-OPTIONS - --grid_type (CS) | ICO + Type of paving stencil to use `LOWCONN`, `CUBIT` or `LOWCONNOLD`. `LOWCONN` provides + a few enhancements over the previous `LOWCONN` old template by removing + spurious elements with high aspect ratios (typically near interior corners). +
- Type of base mesh to use for refinement: cubed-sphere (CS) or icosahedral - (ICO). If ICO is specified, generate a basic icosahedral flag mesh. All - refinement criteria will be ignored in this case. +`--refine_level ` +
- --refine_type (LOWCONN) | CUBIT | LOWCONNOLD + Number of levels of refinement to use in grid generation. Each refinement + level corresponds to a 2x refinement of the mesh. +
- Type of paving stencil to use LOWCONN, CUBIT or LOWCONNOLD. LOWCONN provides - a few enhancements over the previous LOWCONN old template by removing - spurious elements with high aspect ratios (typically near interior corners). +`--resolution ` +
- --refine_level + Base resolution of the mesh. For cubed-sphere meshes this corresponds to the + number of faces along each edge of the cubed-sphere. +
- Number of levels of refinement to use in grid generation. Each refinement - level corresponds to a 2x refinement of the mesh. +`--refine_file ` +
- --resolution + Filename of the PNG file to use for specifying refinement regions. +
- Base resolution of the mesh. For cubed-sphere meshes this corresponds to the - number of faces along each edge of the cubed-sphere. - - --refine_file +`--refine_rect ` +
- Filename of the PNG file to use for specifying refinement regions. + An argument specifying rectangular regions on the cubed-sphere where + refinement should be applied. Each refine_rect should be separated by a + semi-colon and consists of five arguments: - --refine_rect + ``` + ,,,, + ``` - An argument specifying rectangular regions on the cubed-sphere where - refinement should be applied. Each refine_rect should be separated by a - semi-colon and consists of five arguments: - - ,,,, + where `,` are the longitude-latitude coordinates of the lower-right + corner of the refinement region, `,` are the longitude-latitude + coordinates of the upper-right corner of the refinement region, and `` + is the number of levels of refinement. +
- where , are the longitude-latitude coordinates of the lower-right - corner of the refinement region, , are the longitude-latitude - coordinates of the upper-right corner of the refinement region, and - is the number of levels of refinement. +`--output ` +
- --output + Filename for the output EXODUS-format grid file. +
- Filename for the output EXODUS-format grid file. +`--loadcsrefinementmap` +
- --loadcsrefinementmap + (ADVANCED) If specified, the refinement map will be reloaded from the + previously generated refine_map.dat file. This option allows for manual + editing of the cubed-sphere refine map. +
- (ADVANCED) If specified, the refinement map will be reloaded from the - previously generated refine_map.dat file. This option allows for manual - editing of the cubed-sphere refine map. +`--smooth_type (NONE) | SPRING` +
- --smooth_type (NONE) | SPRING + If `SPRING` is specified, use spring-dynamics type mesh smoothing once the + refined mesh has been generated. +
- If SPRING is specified, use spring-dynamics type mesh smoothing once the - refined mesh has been generated. +`--smooth_dist ` +
- --smooth_dist + By default (smooth dist 1) only nodes which are part of the transition region + will be smoothed. Larger values of smooth_dist includes nodes of distance + smooth_dist away from the transition region (by edge connectivity). If + smooth_dist is set to -1 then the entire mesh will be subjected to smoothing. +
- By default (smooth dist 1) only nodes which are part of the transition region - will be smoothed. Larger values of smooth_dist includes nodes of distance - smooth_dist away from the transition region (by edge connectivity). If - smooth_dist is set to -1 then the entire mesh will be subjected to smoothing. +`--smooth_iter ` +
- --smooth_iter + Number of smoothing iterations to perform. A larger value will typically + result in a smoother mesh. +
- Number of smoothing iterations to perform. A larger value will typically - result in a smoother mesh. +`--lon_base ` +
- --lon_base + Longitude coordinate (in degrees) of the left-most edge of the PNG image. +
- Longitude coordinate (in degrees) of the left-most edge of the PNG image. +`--lon_shift ` +
- --lon_shift + Amount of rotation (in degrees) to apply to the base mesh. +
- Amount of rotation (in degrees) to apply to the base mesh. +`--lon_ref ` +
- --lon_ref + The central longitude of the first panel of the cubed-sphere (in degrees). +
- The central longitude of the first panel of the cubed-sphere (in degrees). - - --lat_ref +`--lat_ref ` +
- The central latitude of the first panel of the cubed-sphere (in degrees). + The central latitude of the first panel of the cubed-sphere (in degrees). +
- --orient_ref +`--orient_ref ` +
- The orientation of the cubed sphere at , in degrees. - A value of 0 means the cubed-sphere is aligned perfectly zonal at the\ - reference point. A value of 45 means the cubed-sphere is inclined by 45 - degrees at this point. - - --invert + The orientation of the cubed sphere at `,` in degrees. + A value of 0 means the cubed-sphere is aligned perfectly zonal at the + reference point. A value of 45 means the cubed-sphere is inclined by 45 + degrees at this point. +
- Invert the base image (so black identifies regions of refinement). +`--invert` +
- --block_refine + Invert the base image (so black identifies regions of refinement). +
- Turn on block-wise tagging of elements for refinement. +`--block_refine` +
+ Turn on block-wise tagging of elements for refinement. +
diff --git a/src/SQuadGen.cpp b/src/SQuadGen.cpp index bd7b6ba..02f213f 100644 --- a/src/SQuadGen.cpp +++ b/src/SQuadGen.cpp @@ -14,7 +14,6 @@ /// or implied warranty. /// -#include #include "netcdfcpp.h" #include