|
1 | | -# Building HydroChrono with Project Chrono and HDF5 files |
| 1 | +# What is HydroChrono? |
2 | 2 |
|
3 | | -## Prerequisites |
4 | | -1. Chrono installed and built in RelWithDebInfo mode v8.0.0 (built with Irrlicht module) and Chrono dependencies (see [Chrono Install/Build Guide for details](https://api.projectchrono.org/tutorial_install_chrono.html) ). This includes items like |
5 | | - * C++ Compiler (Visual Studio 2019 or newer required, 2019 recommended) |
6 | | - * Eigen3 (3.3.0 or newer required, 3.4.0 recommended) |
7 | | - * Irrlicht Engine (1.8.4) |
8 | | - * CMake |
9 | | - * GIT client |
| 3 | +HydroChrono is an advanced hydrodynamics package for simulating complex ocean systems. Its designed to integrate seamlessly with the open-source physics engine, [Project Chrono](https://projectchrono.org/) through a robust C++ API. |
10 | 4 |
|
11 | | -2. Install H5Cpp header file from HDF5Group Note: Version 1.10.8 recommended, other versions may not work as intended. [Download Link](https://portal.hdfgroup.org/display/support/Downloads) [Instructions](https://portal.hdfgroup.org/display/support/Building+HDF5+with+CMake#BuildingHDF5withCMake-quickins) Note 2: **This is why Visual Studio 2019 is recommended above**, building HDF5 with newer versions of Visual Studio is not as clear (TODO: add VS2022 instructions). To clarify the HDF5Group setup/build instructions here is a short summary of the steps: |
12 | | - 1. Extract zip somewhere |
13 | | - 2. Go into `<path>\libraries\CMake-hdf5-1.10.8\CMake-hdf5-1.10.8` which contains .bat files etc and open command line (SHIFT + right click, open powershell window on windows) |
14 | | - 3. Execute the batch file or shell script for your platform. For example, `ctest -S HDF5config.cmake,BUILD_GENERATOR=VS201964 -C RelWithDebInfo -V -O hdf5.log` |
15 | | - 4. Config `RelWithDebInfo` is the recommended configuration to allow running in Release mode or a debug mode (RelWithDebInfo). |
16 | | - 5. Wait for it to configure everything and run all its tests, most should pass. |
17 | | - 6. Locate and uncompress built binary its name is `HDF5-N-<platform>.<zip or tar.gz>` it appears in 2 locations, make sure to unzip the one in the build folder! |
18 | | - 7. Navagate to `<path>\libraries\CMake-hdf5-1.10.8\CMake-hdf5-1.10.8\build\HDF5-1.10.8-win64\HDF5-1.10.8-win64\share\cmake` or similar location to the cmake folder. Check that `hdf5-config.cmake` files are here. |
19 | | - 8. In general, to use HDF5 library users must first set the `HDF5_DIR` environment variable to the installed location of the CMake configuration files for HDF5. For example, on Windows the following path might be set: |
20 | | - * `HDF5_DIR=C:\Users\USER\code\libraries\CMake-hdf5-1.10.8\CMake-hdf5-1.10.8\build\HDF5-1.10.8-win64\HDF5-1.10.8-win64\share\cmake` |
| 5 | +# Capabilities of HydroChrono |
21 | 6 |
|
22 | | -3. Recommended (For use with Python): Install and build PyChrono according to [instructions.](https://api.projectchrono.org/module_python_installation.html) Note, instructions for building PyChrono include installing SWIG to generate python files-this is used again to generate python from HydroChrono C++ code. |
| 7 | +With HydroChrono, you can model any system that's supported by Chrono - from multiple bodies and joints to finite element bodies and discrete element particles. HydroChrono will supply hydrodynamic forces to any rigid body in the system - whether you're looking to simulate multibody wave energy converters (WECs) or floating offshore wind turbines (FOWTs) with flexible towers and blades through Chrono::FEA. |
23 | 8 |
|
24 | | -* (optional) Gnuplot [Gnuplot Home](http://www.gnuplot.info/) or other plotting software |
| 9 | +# Dive Deeper 🏊♂️ |
25 | 10 |
|
26 | | -## Building HydroChrono (and demos) |
27 | | -1. Install and build above requirements, exact versions listed are required for proper functionality. |
28 | | -2. Now to build HydroChrono library: |
29 | | - 1. Clone this project into a directory, and set up a build folder (i.e. clone project into HydroChrono directory and set up HydroChrono_build adjacent directory). |
30 | | - 2. Just like when building Project Chrono, open CMake GUI specifying the location of the source files and built binaries for HydroChrono (HydroChrono and HydroChrono_build respectively). Configure and generate the solution setting |
31 | | - * `Chrono_DIR` as Chrono Build location (`../chrono_build/cmake`) |
32 | | - * HDF5_DIR as (`../CMake-hdf5-1.10.8/CMake-hdf5-1.10.8/build/HDF5-1.10.8-win64/HDF5-1.10.8-win64/share/cmake` or similar path to find the `cmake` file at the end of this path). Note: version 1.10.8 of HDF5 works best with Visual Studio 2019. |
33 | | - * Enable `HYDROCHRONO_ENABLE_DEMOS`, `HYDROCHRONO_ENABLE_IRRLICHT`, and `HYDROCHRONO_ENABLE_TESTS` to enable each feature. it is recommended to enable all of these, and the Irrlicht module depends on having Project Chrono be built with Irrlicht module enabled. |
34 | | - 3. Navigate to the build folder and open the solution in Visual Studio (or simply press "Open Project" in CMake GUI). Build the solution for HydroChrono in RelWithDebInfo mode (The `ALL_BUILD` project is the best for building and linking everything). |
35 | | -3. From Project Chrono build directory copy `chrono_build/bin/data` file into `HydroChrono_build/data` for optional shaders and logos |
36 | | -4. Navigate to `chrono_build/bin/RelWithDebInfo` folder and copy all .dll and .pdb files (not for demos) and paste them into `HydroChrono_build/demos/RelWithDebInfo` file. List of all files to copy: |
37 | | - * ChronoEngine.dll |
38 | | - * ChronoEngine.pdb |
39 | | - * ChronoEngine_irrlicht.dll |
40 | | - * ChronoEngine_irrlicht.pdb |
41 | | - * ChronoEngine_postprocess.dll |
42 | | - * ChronoEngine_postprocess.pdb |
43 | | - * Irrlicht.dll (no pdb for Irrlicht) |
44 | | - * and any other chrono module ChronoEngine_moduleName.dll and ChronoEngine_moduleName.pdb |
45 | | -5. Navigate to `HydroChrono_build/demos/RelWithDebInfo` and run demos. |
46 | | - * When running demos, a command line argument is needed for the location of input files. To set this, run demo executables from the command line with the command argument for the absolute file location for `<path>/HydroChrono/demos` (Ex: the command `> ./sphere_decay.exe C:\Users\USERNAME\HydroChrono\demos` when executed from the `HydroChrono_build/demos/RelWithDebInfo` file will run the sphere heave decay test demo with the proper input file locations.) |
47 | | - * Alternatively, set the command line argument for debug mode in a demo's properties. Do this in Visual Studio 2019 by navigating to the solution explorer, right clicking a demo, select `properties > Configuration Properties > Debugging` and set the option for Command Arguments to `C:\Users\USERNAME\HydroChrono\demos`. |
48 | | - * Optionally copy plot files into results files and generate plots. |
| 11 | +For more detailed information about HydroChrono please visit the [HydroChrono website](https://nrel.github.io/HydroChrono/). This website covers the theory behind the code in more detail, along with instructions for how to build the code and start using it. |
49 | 12 |
|
50 | | -## Tests |
| 13 | +As of now, HydroChrono must be built from source. While this provides flexibility for customization and optimization, it also means that the setup process may be more involved than a pre-compiled solution. For detailed build instructions, please refer to our HydroChrono website. We are continually working to improve the installation process and appreciate your feedback and patience! |
51 | 14 |
|
52 | | -If `HYDROCHRONO_ENABLE_TESTS` is enabled during configuration (need python) you can launch every tests in the build directory with the command on Linux: |
| 15 | +# Limitations of HydroChrono |
53 | 16 |
|
54 | | - ctest . |
| 17 | +Like all tools, HydroChrono has its own set of limitations: |
55 | 18 |
|
56 | | -and on Windows: |
| 19 | +- **First-order potential flow forces:** we currently support first-order potential flow forces; more complex/nonlinear options have not yet been implemented. |
| 20 | +- **Rigid bodies:** while flexible bodies can be included in a system, at the moment we only support hydrodynamic forces applied to rigid bodies. |
57 | 21 |
|
58 | | - ctest -C <config> |
| 22 | +We welcome feedback and contributions to help us address these limitations! |
59 | 23 |
|
60 | | -Where <config> is the build configuration (i.e. "Debug", "Release", etc.) |
| 24 | +# Long-term Goals & Vision |
61 | 25 |
|
62 | | -To launch only a subset of the tests (demos, examples, small, medium, long): |
63 | | - |
64 | | - ctest -L demos -L medium |
65 | | - |
66 | | - |
67 | | - |
68 | | - |
69 | | - |
70 | | -## Files |
71 | | -* src - contains source code for HydroChrono library |
72 | | - * hydro_forces.cpp |
73 | | - * Defines classes to calculate hydrodynamic forces and apply to a multibody system. |
74 | | - * chloadaddedmass.cpp |
75 | | - * Defines a class to apply the added mass at infinite frequency to a system using Project Chrono Loadable objects. |
76 | | - * h5fileinfo.cpp |
77 | | - * Defines a class to read an h5 file and store system properties. |
78 | | - * helper.cpp |
79 | | - * Defines helper functions for various operations. |
80 | | -* include/hydroc - contains header files for above corresponding .cpp files. |
81 | | -* demos - contains information for various demos |
82 | | - * demos/rm3 - contains required files for rm3 demos (decay test and regular wave test) |
83 | | - * rm3_decay.cpp and rm3_reg_waves.cpp - demos showing rm3 decay and regular wave test respectively |
84 | | - * demos/rm3/geometry - .obj files defining verticies on rm3 objects |
85 | | - * demos/rm3/hydroData - contains rm3.h5 file |
86 | | - * demos/rm3/postprocessing - contains .plt plotting files and WEC-Sim comparison data for plots. Copy these into results folder to plot demo outputs |
87 | | - * demos/sphere - contains required files for sphere demos (decay test and regular wave test) |
88 | | - * sphere_decay.cpp and sphere_reg_waves.cpp - demos showing sphere decay and regular wave test respectively |
89 | | - * demos/sphere/geometry - .obj files defining verticies on sphere object |
90 | | - * demos/sphere/hydroData - contains sphere.h5 file |
91 | | - * demos/sphere/postprocessing - contains .plt and .py plotting files and WEC-Sim comparison data for plots. Copy these into results folder to plot demo outputs |
92 | | - * demos/f3of - contains required files for f3of demo (decay test and regular wave test) |
93 | | - * F3OF.cpp - demo showing f3of decay, optionally add regular waves |
94 | | - * demos/f3of/geometry - .obj files defining verticies on f3of objects |
95 | | - * demos/f3of/hydroData - contains f3of.h5 file |
96 | | - * demos/f3of/postprocessing - contains .plt plotting files and WEC-Sim comparison data for plots. Copy these into results folder to plot demo outputs |
97 | | - * demos/oswec - contains required files for oswec demo (decay test) |
98 | | - * oswec_decay.cpp - demo showing oswec decay and optionally regular waves |
99 | | - * demos/oswec/geometry - .obj files defining verticies on oswec object |
100 | | - * demos/oswec/hydroData - contains oswec.h5 file |
101 | | - * demos/oswec/postprocessing - contains .plt and .py plotting files and WEC-Sim comparison data for plots. Copy these into results folder to plot demo outputs |
102 | | - * demos/Test - can be ignored |
103 | | - * demos/python - can be ignored for now |
104 | | -* tests - contains multiple base tests used when option `HYDROCHRONO_ENABLE_TESTS` is enabled |
| 26 | +- **Develop advanced simulation capabilities:** HydroChrono opens up several new simulation possibilities, including: |
| 27 | + - Simulation of anchor-seabed interactions for WECs and FOWTs using both the DEM (Discrete Element Method) and FEA (Finite Element Analysis) modules available in Project Chrono. |
| 28 | + - Distributed hydrodynamic loads on flexible structures through the use of Chrono::FEA. This not only allows for in-depth structural analysis but also the simulation of innovative deformable and/or inflatable WECs. |
| 29 | +- **Deeper Integration with the Chrono Ecosystem:** We envision a seamless transition of system models across various fluid dynamics realms. From HydroChrono's potential flow to Computational Fluid Dynamics (CFD) and Smoothed Particle Hydrodynamics (SPH), our goal is to offer detailed Fluid-Structure Interaction (FSI) insights. This will aid researchers in understanding intricate nonlinear FSI scenarios before actual ocean deployments. Additionally, we want to support rapid estimation of viscous drag coefficients to help refine HydroChrono's potential flow models. |
| 30 | +- **Expanding Accessibility with a Python API:** Recognizing the global research community's diverse coding preferences, we're working towards introducing a Python API for HydroChrono. This will provide a more accessible interface and reduce the reliance on C++ for many users. |
| 31 | +- **Advocating for Open-Source Collaboration:** At the heart of HydroChrono lies the spirit of innovation driven by open-source collaboration. We highly value open-source solutions and strongly encourage collaborations! |
0 commit comments