Rewrite readme (focus on getting started with the Release binaries) and add some screenshots

Author: dav-og

README.md

@@ -1,100 +1,128 @@
-# HydroChrono
 
-**HydroChrono** is an emerging hydrodynamics simulation tool designed to model complex ocean systems. Seamlessly integrated with the [Project Chrono](https://projectchrono.org/) physics engine, it offers a powerful C++ API for a wide range of simulations.
+<p align="center">
+  <img src="docs/assets/img/hydrochrono_banner.png" />
+  <br/>
+  <a href="https://github.com/NREL/HydroChrono/releases"><img src="https://img.shields.io/badge/version-v0.3-blue.svg" /></a>
+  <a href="#"><img src="https://img.shields.io/badge/status-Prototype-orange.svg" /></a>
+</p>
 
-## Capabilities
+> [!NOTE]
+> HydroChrono is under active development (v0.3 prototype). This early release focuses on a YAML‑driven CLI and portable HDF5 outputs so you can try the code and share feedback. Expect rapid iteration over the coming year — please open issues/feature requests and join discussions.
+> 
+> • Issues: https://github.com/NREL/HydroChrono/issues  
+> • Discussions: https://github.com/NREL/HydroChrono/discussions
 
-HydroChrono extends the versatility of Project Chrono to hydrodynamic applications, enabling you to simulate multibody wave energy converters (WECs) and floating offshore wind turbines (FOWTs) with Chrono::FEA for flexible bodies.
+HydroChrono (Hydrodynamics for Project Chrono) is a hydrodynamics simulation toolkit built on [Project Chrono](https://projectchrono.org/). This repo ships a prototype, YAML‑driven CLI app for running simulations and exporting portable results.
 
-## Get Started
+## What it does (under the hood)
 
-Visit the [HydroChrono website](https://nrel.github.io/HydroChrono/) for information about the underlying theory, build instructions, and usage details. Currently, HydroChrono is available as a source build, offering customization and optimization opportunities. A binary distribution with Python wrapper is in development and coming soon.
+- Uses Boundary Element Method (BEM) hydrodynamic coefficients (e.g., from [Capytaine](https://github.com/capytaine/capytaine)) to describe added mass, radiation damping, and wave excitation. HydroChrono reads these coefficients from BEMIO‑format HDF5 (.h5) files, an approach familiar to [WEC‑Sim](https://github.com/WEC-Sim/WEC-Sim) users.
+- Runs time‑domain simulations via the Cummins equation (impulse‑response/convolution form for radiation effects).
+- Builds complex, nonlinear multibody systems using Project Chrono; hydrodynamic loads are currently first‑order, with expanded models planned.
+- Exports portable results to HDF5 for post‑processing and validation.
 
-## Limitations
+## Download
 
-- Currently only supports first-order linear potential flow forces.
-- Hydrodynamic forces are currently limited to rigid bodies.
+- Get the latest Windows binaries from the [Releases](https://github.com/NREL/HydroChrono/releases) page.
 
-## Vision and Future Goals
+## Quick start (CLI)
 
-- Expand hydrodynamics to incorporate nonlinear and 2nd order forces.
-- Integrate advanced simulation features using Project Chrono's DEM and FEA modules.
-- Support seamless transitioning from potential flow to CFD and SPH for detailed FSI analysis.
-- Develop a Python API to broaden accessibility and ease of use.
-- Foster and support open-source collaboration in the research community.
+After downloading, open a terminal in the app folder and run:
 
-## Build Instructions
+```powershell
+run_hydrochrono.exe -h     # help
+run_hydrochrono.exe -i     # info/banner
+
+# Run a case by directory (auto-detects setup)
+run_hydrochrono.exe .\cases\my_model\
+
+# Or run directly from a setup file
+run_hydrochrono.exe .\cases\my_model\my_model.setup.yaml
+
+# Useful options
+run_hydrochrono.exe .\cases\my_model\ --nogui --output-h5 results.h5
+```
 
-### Prerequisites
+### CLI Example
 
-- **Visual Studio 2022** with C++ toolchain
-- **CMake 3.18+**
-- **Project Chrono** (built from source; tested v9.0.0–v9.0.1)
-- **HDF5 1.10.8+**
-- **Eigen 3.4+** (header-only unzip is fine)
-- **Irrlicht 1.8.x** (optional but required for GUI helper)
-- **Python 3.8+** (only for docs/tools)
+The CLI prints a concise summary of what will run so you can check inputs and spot mistakes quickly:
 
-### Building from Source (using `build-config.json` + script)
+- Banner and version/status
+- Input summary: directory or setup file, resolved `*.model.yaml`, `*.simulation.yaml`, `*.hydro.yaml`, output directory
+- Simulation summary: bodies, constraints, estimated DoFs, time step, duration
+- Hydrodynamic data summary (from HDF5): file name, number of bodies, DoFs/body, frequency count, IRF/excitation/radiation/added‑mass flags
+- Wave model summary (type, height, period or spectrum)
+- Start/complete markers with steps and wall time; exported HDF5 path echoed for traceability
 
-1. **Clone the repository**
-   ```powershell
-   git clone https://github.com/NREL/HydroChrono.git
-   cd HydroChrono
-   ```
+Tips: use `--quiet` to reduce logs, `--debug`/`--trace` for deeper diagnostics.
 
-2. **Create your local config from the example**
-   ```powershell
-   copy build-config.example.json build-config.json
-   ```
+<p align="center"><img src="docs/assets/img/cli_example.png" width="75%" /></p>
 
-3. **Edit `build-config.json`** and set paths for your machine
+### GUI Example
 
-   **Example:**
-   ```json
-   {
-     "ChronoDir": "C:/path/to/chrono/build/cmake",
-     "Hdf5Dir": "C:/path/to/hdf5/share/cmake",
-     "EigenDir": "C:/path/to/eigen-3.4.0",
-     "IrrlichtDir": "C:/path/to/irrlicht-1.8.4",
-     "PythonRoot": "C:/Users/<you>/.conda/envs/<env>",
-     "CMakeModulePath": "C:/path/to/chrono/build/cmake"
-   }
-   ```
+Use the GUI to visually inspect the assembled multibody system (bodies, joints, actuators) and verify that YAML inputs are wired correctly. Use the `--nogui` option to disable visualization straight from CLI, or change the settings in the `*.simulation.yaml` file.
 
-4. **Build (from repo root)**
+<p align="center"><img src="docs/assets/img/gui_example.png" width="40%" /></p>
 
-   - Clean configure + build (default `Release`):
-     ```powershell
-     .\quick-build.ps1 -Clean
-     ```
-   - Build a different configuration (e.g., `Debug`):
-     ```powershell
-     .\quick-build.ps1 -BuildType Debug
-     ```
 
-4. **Post-Build Steps**
+## YAML-based UI
 
-Copy the following DLL files from your Chrono build directory to your build directory's `build/bin` folder:
-- ChronoEngine.dll
-- ChronoEngine_irrlicht.dll (if using Irrlicht)
-- Irrlicht.dll (if using Irrlicht)
+HydroChrono uses separate YAML files so you can describe a mechanical system once and run it across different hydrodynamic backends (potential flow today; SPH/CFD next). This keeps your Chrono model clean and reusable. Everything is defined in text based files - making it easier to automate.
 
-5. **Run the tests**
-   ```powershell
-   cd build
-   ctest -C Release
-   ```
+```
+cases/my_model/
+  my_model.setup.yaml       # references the files below (recommended)
+  my_model.model.yaml       # bodies, joints, actuators
+  my_model.simulation.yaml  # time step, duration, GUI, waves
+  my_model.hydro.yaml       # hydrodynamics
+```
 
----
+- `my_model.setup.yaml` — simulation 'orchestrator'
+  - Specifies the input files you want to run
+- `my_model.model.yaml` — the multibody system
+  - Bodies, joints, constraints, actuators, sensors (pure Chrono)
+- `my_model.simulation.yaml` — how to run it
+  - Time step, duration, output options, GUI flags (pure Chrono)
+- `my_model.hydro.yaml` — hydrodynamics inputs
+  - BEMIO `.h5` path (e.g., from Capytaine), body ↔ hydrodynamic body mapping, desired wave inputs
 
-### Clean Build
 
+Run with either the folder path (auto-detects `*.setup.yaml`) or the setup file directly:
 ```powershell
-# From the project root
-Remove-Item -Recurse -Force build
-# then reconfigure/build
-.\quick-build.ps1 -Clean
+run_hydrochrono.exe .\cases\my_model\
+run_hydrochrono.exe .\cases\my_model\my_model.setup.yaml
 ```
 
-For more detailed build instructions, including Visual Studio setup and running demos, see the [developer documentation](https://nrel.github.io/HydroChrono/developer_docs/build_instructions.html).
+### Example *.model.yaml file
+
+<p align="center"><img src="docs/assets/img/yaml_example.png" width="25%" /></p>
+
+
+## HDF5 outputs (portable)
+
+- Simulations produce a single `.h5` file with time series and model results.
+- Typical datasets include:
+  - body position (XYZ):
+    - `/results/model/bodies/<body_name>/position` (columns 0..2)
+  - body orientation (roll, pitch, yaw):
+    - `/results/model/bodies/<body_name>/orientation_xyz` (columns 0..2)
+  - translational spring–dampers:
+    - `/results/model/tsdas/<actuator_name>/` (force components, extension, speed, etc.)
+  - rotational spring–dampers:
+    - `/results/model/rsdas/<actuator_name>/` (torque components, angle, angular_velocity, etc.)
+- View/plot with HDFView or VS Code HDF5 extensions.
+  - HDFView: `https://www.hdfgroup.org/downloads/hdfview/`
+
+<p align="center"><img src="docs/assets/img/h5_example.png" width="75%" /></p>
+
+## Examples
+
+- Additional ready‑to‑run cases will be included on the Releases page.
+- They double as regression tests:
+  ```powershell
+  python .\run_tests.py --all
+  ```
+
+## Developers
+
+- Full build and contribution docs: [Developer documentation](https://nrel.github.io/HydroChrono/developer_docs/build_instructions.html)