rsvs3D
0.0.0
Codes for the c++ implementation of the 3D RSVS
|
The 3D-RSVS is a geometry generation tool using volume specification to build smooth surfaces. Papers describing the method are available on researchgate and ScienceDirect.
Last updated 25/07/2021 Full documentation available.
This repository is the C++ implementation of the 3D R-Snake Volume of Solid (RSVS) parameterisation. It includes a main executable that can be built from the SRCC
directory and Matlab support codes in SRCMAT
. Building and using the 3D-RSVS does not require the MATLAB code is here as it was used to prototype and test ideas.
Relevant publications for the 2D RSVS are at the end of this readme.
The compiled binary is available for download for Windows 64bits and Linux 64bits. This program provides both a command line interface (CLI) and a GUI for visualising your results.
An example of using the GUI to visualise and configure the 3D-RSVS is presented in a video tour on YouTube. The 3D-RSVS program is available as a binary from the latest build
This project uses git submodules to handle dependencies:
git clone --recurse-submodules https://github.com/payoto/rsvs3d
or
git clone https://github.com/payoto/rsvs3d git submodule update --init --recursive
If you are using VS code and are looking to develop the project, my settings for this workspace are stored in this gist.
For this code to work necessary programs:
make
to build the RSVS3D
executable.Additional software used for plotting and prototyping:
SRCMAT
.lay
filesRequired 3rd party open source libraries for compilation (dependencies available at github/payoto/rsvs3d-dependencies
):
(Optional) 3rd party open source library:
All dependencies are intended to be handled via git submodules, to install them using submodules, run git submodule update --init --recursive
.
All these dependencies may not be needed but this is what it took:
In order to build on MACOS you will need an X11
library, this can be installed with: brew install --cask xquartz
using the brew package manager.
Any code using the Tetgen interface and functionalities is under the GNU Affero GPL license which is more restrictive than the LGPL of this project (this is not legal advice, but my understanding):
Refer to the full License terms for real information.
:note: If the LGPL is too restrictive for you get in touch and I can move the code I own to something more permissive.
You will need make
and a gcc
toolchain for the default compilation to work on windows you can use chocolatey to install them. Run choco install make mingw
in an elevated powershell once chocolatey is installed or check the windows github action for details.
To Compile and test the C++ code:
For more notes on compilation flags see SRCC/README.md. If the short tests run (they should), to see some example usages pass the --help
flag:
:note: replace RSVS3D
with RSVS3D.exe
on windows.
Before being able to call the Matlab codes (these are not necessary for the geometry tool execution) you will need to call these in the matlab console.
>> Init3DMatlab >> Include_3DCheckGrid
the Include_XXXX
files "import" all the local functions defined inside them into the matlab workspace avoiding the need to create one matlab file per function.
Read the (sparse) documentation, read Chapter 7 of "Shape and Topology Optimisation of External Flows" (thesis) also available as a standalone PDF of finally use the issues board.
No release of the RSVS has been made as there are a number of known stability and convergence issues which means that it is unlikely to work beyond the specific test cases that were studied in Chapter 7 of the thesis.
For a discussion of those limitations see Chapter 7
Generating a geoemtry using the 3D-RSVS method only requires the executable RSVS3D.exe
. For basic usage information from the command line use:
RSVS3D --help
:Note: Running RSVS3D
with no command line arguments does nothing.
This will create in the output folder reported at the start of the execution the following geometry
The output can be visualised using Tecplot by opening the file:
../out/Archive_XX/Day_XX/rsvs3d_<time>_sphere2/RSVS_loglvl3_<time>_sphere2.lay
Below are all the possible commad line options for the RSVS3D program. These can be assembled in arbitrary ways to run a specific config. The long name is shown (called with prefixed --
on the command line) followed by
-h
): Display command line help;-n
): Do not run the RSVS process and output the configuration file;-e
): Execute the RSVS3D for the default case;-i
): Execute the RSVS process in interactive mode using a GUI;-u
): Use system configuration STRING
(none specified yet);-l
): Load a configuration file from FILE
;-p
): Overwrite a specific parameter specified by KEY:VAL
. "key" is the name of that paramaeter as it appears in the flattened JSON parameter files, "val" is the value of that patameter;new
, short
or all
. May be disabled in releases.Internally parameters are controlled by a single structure defined in parameters.h. Externally parameters are handled using JSON files. These provide a good balance of human and machine readable format. And support intricate tree structures and nesting. The JSON interaction is handled by an external library JSON for Modern C++. This library allows two types of JSON files: normal and flat. Default parameter configuration files showing all the parameters and there default options in default_config and default_configflat. Below are two JSON examples.
Example normal JSON:
Equivalent flat JSON:
Three command line options are currently available for parameter control: the use-config, load-config and param give control over the execution of the RSVS. It permits the control of execution flow, output level and output location as well as specific mesh and volume information. The use-config, load-config and param options can be combined to get the desired set of parameters, multiple ones of each can be called. The program throws an error if a parameter is not recognised or not correctly read from a file. These 3 types of options are parsed in order of their appearance in the help and this (readme): use-config then load-config and finally param. Inputs of the same type are then parsed in their order of appearance.
Load-config can load an incomplete set of parameters overwriting only parameters that are specified.
For up to date parameter list check the default configuration files.
Controls the file interaction of the program including the naming of output folders.
appcasename2outdir
: append casename to output dir path?casename
: Name of the case.snakemeshname
: Mesh file to load.targetfill
: Unused (see rsvs)basenameoutdir
: Name of the output directory.basenamepattern
: time format string added to the basenameoutdir.logginglvl
: Depth of data logging 0-minimal, 1-Logs only, 2-Snake history, 3-All data.outdir
: Leave empty to use the automatic archive directory trees, otherwise the output directory.outputlvl
: Depth of final data output.pathoutdir
: Root directory (relative or absolute) for the archiving tree.pathpattern
: Directory stub to use as a time format which will be assembled to generate an archiving output folder pattern.pattern
: Used internally to store the pattern generated by basenamepattern
.redirectcerr
: redirection of standard error to a file.redirectcout
: redirection of standard output to a file.Control the underlying grid if it is generated. It can also be loaded if "/files/ioin/snakemeshname"
is specified.
activegrid
: The type of grid to build ("voxel"
, "voronoi"
or "load"
).domain
: Domain dimensions, each of x, y and z are represented by a lower and upprt bound.gridsizebackground
: Design grid size on which the volume fractions are specified.gridsizesnake
: Snaking mesh as a refinement of the background mesh.distancebox
: for a voronoi VOS mesh the distance outside domain
at which the bounding points will be placed.inputpoints
: A vector of data containing coordinates used for the Voronoi process.pointfile
: The file from which these are loaded.Examples: gridsizebackground=[2, 3, 4]
and gridsizesnake=[4, 4, 4]
will leed to an actual snaking mesh of [8, 12, 16]
.
Parameters:
RSVS process control. Includes the selection of which volume fraction the 3D-RSVS needs to match.
cstfill
: constant fill in all the volume cells.filefill
: Fill is specified in a file (space delimited data).makefill
: Programmaticaly defined fill information.solveralgorithm
: Chooses the solution process for the Quadratic Problem of the RSVS.Only one of filefill
, makefill
or cstfill
is taken into account if they are all set to active. The order of precendence is:
filefill
makefill
cstfill
Parameters:
Control the restricted snaking process, can have a large impact on the speed and quality of the convergence of the RSVS process.
arrivaltolerance
: Distance from a vertex at which a snaxel is considered "arrived".initboundary
: Initialisation boundary (1 or 0). Which volume fraction boundary should the surface be started at.maxsteps
: Maximum number of snake steps.multiarrivaltolerance
: When two snaxels converge on a vertex what is the radius at which the arrival procedure is triggered.snaxdiststep
: Maximum non-dimensional distance which can be covered by a snaxel in 1 step.snaxtimestep
: Maximum time step (used for damping of the SQP).Parameters
Begginning to use git? Follow these 5mn ELI5 explainer which will help understand what the lingo means, git begginer guide which should get you up and running, or the full git documentation if you're trying to do something git documentation.
Very minimal guide I wrote a while back specific to the repository: Updating your files to be up to date with the master branch can be done using git very efficiently. With a few steps.
git add -u
then git add *.m
then git add Active_Build*png
git commit -m "Add comment about what was done"
git checkout master
git pull
git add -u
and git commit
before the next step)git checkout <your branch name>
git merge master
git add -u
and git commit
)For more information about what the code does (i.e. the science of it):
(Also available on research gate)
Alexandre Payot