Hull Resistance CFD: installation and use

OpenNAOE Hull Resistance CFD

OpenNAOE Hull Resistance CFD (HullCFD) prepares a hull, builds and inspects its mesh, runs a fixed-hull calm-water resistance simulation with OpenFOAM, and reviews or exports the results. Version 1.0.0 - Windows and Linux.

Install on Windows

Requires Intel/AMD 64-bit Windows 10 build 19041 or later, or Windows 11, and internet access to download missing components.

1. Extract the complete ZIP into a local folder. Keep its files together.
2. Double-click INSTALL-WINDOWS.cmd. Read the setup explanation and review the detected Optimize WSL RAM and swap automatically plan. This option is selected by default; it affects all WSL2 apps, preserves other settings and backs up an existing configuration. Tick I understand..., then click Install and open. For an existing installation, choose Install update / repair.
3. Approve any Windows administrator prompt. If a restart is requested, save your work and restart. If setup does not reopen, double-click INSTALL-WINDOWS.cmd after the restart, tick the acknowledgement and click the enabled install/repair button.
4. Open HullCFD from the desktop or the OpenNAOE Start menu folder.

Setup installs or reuses WSL2 and a dedicated OpenNAOE-HullCFD Linux environment with OpenFOAM v2412 (OpenCFD), Python and MPI. Personal Linux environments are kept separate.

The first installation can take tens of minutes. Installed simulations normally work offline.

If setup fails

Check the connection, then choose Retry setup or Continue / repair. Use Show this attempt log or Startup diagnostics to investigate. Keep the Linux environment and saved work in place. After cancelling, wait for the current installation operation to finish before starting another.

Install on Linux (Ubuntu)

The tool needs OpenFOAM v2412 from OpenCFD (openfoam.com), Python 3.12, Open MPI and a C++ compiler (g++, make). Run setup as your normal user from the extracted folder:

bash install-linux.sh

• On Ubuntu 24.04, setup installs any missing system components (it asks for your administrator password), creates the application's Python environment and opens the app.
• On another Linux system, setup works only if all four requirements are already installed; it then reuses them and changes no system packages. The author runs the tool on such a system: Ubuntu 22.04 with OpenFOAM v2412 and Python 3.12, which Ubuntu 22.04 does not include and which he installed separately. This guide gives no installation steps for other systems.

To see what setup will find, run bash packaging/linux-system.sh --check before installing. It exits with 0 when compatible Python 3.12, OpenFOAM v2412, Open MPI and compiler tools are all present, and with 1 otherwise; it changes nothing.

To install OpenFOAM v2412 yourself on Ubuntu 24.04, use OpenCFD's repository, not a same-named package from another OpenFOAM distribution. Download and read the repository script before running it. This release uses OpenFOAM v2412 patch 260127, package version 2412.260127-1, which setup also installs:

curl --fail --location --proto '=https' --tlsv1.2 \
  https://dl.openfoam.com/add-debian-repo.sh -o openfoam-repository.sh
less openfoam-repository.sh
sudo bash openfoam-repository.sh
sudo apt-get install openfoam2412-default=2412.260127-1

If your Ubuntu release offers another build of v2412, the run records name the build used and the hashes of its executables.

On every system, setup then installs the application itself: it copies it to ~/.local/share/OpenNAOE-HullCFD, with its own workspace and a private Python 3.12 environment, and adds HullCFD to your applications menu. On a first installation it downloads the hash-locked Python packages of that environment, so internet access is needed; a later installation reuses a matching environment. If OpenFOAM v2412 is installed somewhere other than /usr/lib/openfoam/openfoam2412 or /opt/OpenFOAM/OpenFOAM-v2412, set SHIPCFD_OPENFOAM_BASHRC=/path/to/v2412/etc/bashrc before running setup. Start the app later from the applications menu, or with bash ~/.local/share/OpenNAOE-HullCFD/opennaoe-hullcfd.sh. The interface listens only on this computer (127.0.0.1).

Run a simulation

1. In Hull, load the example or import an STL/OBJ hull. Check the file units, scale ratio and bow direction.
2. In Condition, set draught, water properties and speeds. Review the waterplane and computed hydrostatics.
3. In Mesh setup, choose the mesh settings. Keep Automatic MPI selection to choose parallel workers from available RAM and CPU limits, or use Manual. Prepare the cases. Coarse geometry check is for inspecting geometry; use Fine or Extra fine for a resistance solve.
4. In Build mesh, build the selected case and inspect its mesh checks and saved 3D mesh. The mesh must pass its checks before solving.
5. In Solve, open Solver settings. Set Simulation end time and Save fields every in simulation seconds. The output interval must divide the end time exactly; for example, 2 s with output every 1 s. Choose Update the current case or Create a new case using this mesh, then click Save solve settings. Check the Saved solve target and click Start fresh solve.
6. After the solve finishes, open Results, select the saved case and click Create analysis. Select the saved analysis to review it, inspect its fields in 3D view, and export the required outputs.

Saving settings retains earlier versions. Start fresh solve begins at 0 s; Continue saved solution extends existing output.

Automatic resource selection preserves the numerical mesh and solver settings. It cannot guarantee that an arbitrary mesh fits. If memory runs out, use Save diagnostics and the case's retry guidance. Increasing MPI workers does not add RAM. Existing cases retain their saved process count.

Save and find your work

The application stores cases, meshes and solver output in its Linux workspace:

• on Windows, /home/opennaoe/.local/share/OpenNAOE-HullCFD/workspace inside its dedicated WSL environment;
• on Linux, ~/.local/share/OpenNAOE-HullCFD/workspace.

Use Project file location to open that workspace in File Explorer (on Linux, in your file manager).

• Save setup and Save mesh settings save the entered settings.
• Save mesh and Save run status save case records; actual mesh and solver files are already saved by the application.
• Save project file writes OpenNAOE-HullCFD.hullcfd in the workspace. Open project file restores its settings and references to saved cases.
• In Results, Save results saves CSV, history and report copies in the case folder. Open results folder opens that location. Export buttons download separate copies through the browser.

Saving opens the destination folder, or provides its path if the file manager cannot open. The save is retained.

Case folders are under workspace/cases/. Keep the Linux workspace in place: a .hullcfd project file references it and does not contain meshes or flow fields. Desktop folders can hold project-file copies and exports.

The named case/settings folder is a browsing index. Windows Explorer can show its Inputs, Mesh and Solve Linux links as small files. Read Case-files.txt there, or choose Solve > Open solver files to open the actual attempt. Serial field saves are numbered directories such as 0.05; parallel saves are inside processor0, processor1, etc. The fixed-hull preset keeps the latest five scheduled full-field saves per solver segment and removes older ones. Force/residual histories are separate. How it works explains every case file, field, export and continuation step.

Remove or permanently delete a case

Remove case is available in the Build mesh and Solve case lists. It hides the case under Removed from workspace and keeps its files. Restore case returns it.

Delete permanently removes every saved version, mesh, solve, analysis and folder of that case. Shared source geometry, preparation history and external exports are kept. Deletion is blocked while the case is active or another case uses its mesh or saved solution. Review the confirmation before deleting.

Reopen or continue a simulation

On Windows, open the HullCFD shortcut. If it cannot connect after a Windows restart, run INSTALL-WINDOWS.cmd and choose Open existing app. On Linux, open HullCFD from the applications menu.

Continue a saved solution

1. In Solve, select the case and choose Continue saved solution.
2. For an interrupted case, choose Recover interrupted case to verify that its old processes have stopped.
3. Click Check complete saved writes. Enter the additional simulation time and review the new total end time. For example, a saved write at 2 s plus 3 s gives a total end time of 5 s.
4. Check the output interval, then click Continue from ... to ....

Continuation retains the previous version and reuses its mesh and complete saved flow fields. Later interrupted progress is lost. Without a complete write, use Start fresh solve at 0 s with the accepted mesh.

Reopening leaves pending jobs paused; use the case controls to resume them. When finished, choose Close application. Closing only the window leaves background work running.

Update or uninstall

To update, finish active work and choose Close application. Extract the new ZIP into its own local folder, run INSTALL-WINDOWS.cmd and choose Install update / repair. Keep the existing Linux environment and workspace. On Linux, run bash install-linux.sh from the new folder; the workspace is kept.

To uninstall on Windows, close the application and run UNINSTALL-WINDOWS.cmd:

• Remove launch icons only removes the shortcuts and keeps the application and saved work.
• Full uninstall removes the listed dedicated Linux environments and application packages. It deletes all projects and outputs inside those environments, together with their Python, OpenFOAM and MPI components. Backup is selected by default; choose a backup folder outside the application and Linux disk folders. Confirm by typing DELETE OpenNAOE.

Shared Windows components, personal Linux environments, backups, logs, downloads and installation records are kept. Shared WSL RAM/swap settings are also kept; their original configuration backup is identified in setup diagnostics.

To uninstall on Linux, close the application, copy anything you want to keep from the workspace, then delete ~/.local/share/OpenNAOE-HullCFD (this deletes the workspace and all its cases) and ~/.local/share/applications/opennaoe-hullcfd.desktop. Setup leaves the system packages it installed and the OpenCFD package source it added. Remove packages that no other software needs with apt, for example OpenFOAM v2412:

sudo apt-get remove openfoam2412-default openfoam2412 \
  openfoam2412-common openfoam2412-tools

apt does not remove the package source. If no other software installs from the OpenCFD repository, delete its two files and refresh the package lists:

sudo rm /etc/apt/sources.list.d/opennaoe-openfoam.sources \
  /etc/apt/keyrings/opennaoe-openfoam.gpg
sudo apt-get update

Using the results

This tool supports learning, teaching and early design exploration of calm-water resistance by CFD, compared with model-test measurements for the KCS and DTC hulls. The numerical uncertainty of a run is not established; check the mesh, time step and convergence of each case, and qualify the tool further before real-world engineering use.

See Verification and validation and validation evidence (docs/validation.md in the download).

Detailed controls and cluster runs: Using the application. Setup details: Installation, repair and removal.

Free to use under the OpenNAOE Tool Licence 1.0 (LICENSE): not for modification or redistribution; point others to opennaoe.org. The case templates in templates/ and the cluster run scripts scripts/run_mesh.sh and scripts/run_solve_time_accurate.sh are under GPL-3.0-or-later; LICENSING.md explains the boundary, and NOTICE lists the third-party notices and where their licence texts are.

Installation, repair and removal

This guide covers setup on 64-bit Windows with WSL2; README.md describes setup on Linux. Internet access is required to download missing components. Compatible installations and verified downloads are reused. The package contains the application and its setup scripts for Windows and Linux.

Release 1.0.0. The author has installed and run it on a clean Windows computer, and he runs the tool natively on Ubuntu 22.04. These are his statements: the package's RELEASE.json lists them as such and records no qualification run. No complete reference-hull solve prepared in the interface has been compared with the measurements; see the validation evidence (docs/validation.md).

Install and open

1. Connect to the internet and extract the entire ZIP into a new local folder; keep its files together.
2. Open INSTALL-WINDOWS.cmd. Review the component scope and select the initially unchecked, required I understand… acknowledgement, then choose Install and open. The install/repair button is disabled until it is checked; the acknowledgement is locked while setup runs. This does not make the required dependencies optional. Review the separate, initially selected Optimize WSL RAM and swap automatically option and its detected plan. Opening an already installed app and reviewing uninstall options do not require installation acknowledgement.
3. Setup detects compatible components and installs missing requirements in the verified, separate Hull Resistance CFD engine. Required Windows support changes ask for administrator approval under the same Windows account; another account is refused. A required restart saves continuation.
4. After successful startup, use the desktop or Start menu HullCFD shortcut. Open existing app retries the verified installed version and refreshes its shortcuts without installing requirements. Install update / repair installs the version supplied in the extracted ZIP.

Setup and removal start from CMD files, which run PowerShell scripts that Windows or workplace policy can check; do not disable protection. Edge app mode provides an application window. A browser fallback requires a choice; setup does not install or remove a browser silently. Setup supports x64 Windows with WSL2 and the separate Ubuntu engine. It stops on an ARM-based Windows computer, and the package has no setup for macOS.

Components and ownership

The component view reports observed origin: previously present, installed by a recorded successful setup, or unknown. Presence is not proof that a shared tool is exclusive to this app. This build offers read-only component information, normal application closure, shortcut-only removal and full uninstall of verified private engines and app packages. Shared Windows support is retained.

Automatic resource plan

Setup and the launcher read installed/free Windows RAM and CPU counts through CIM with a bounded wait. Linux supplies its active memory, swap and execution limits. Missing Windows data leaves shared settings unchanged; Linux detection still supplies conservative defaults.

For detected RAM of at least 6 GiB, the plan reserves the greater of 4 GiB or 25% (rounded up) for Windows. WSL receives the remaining whole GiB. Swap is 25% rounded up, with a 4–16 GiB range. Higher existing explicit limits are kept. Swap changes require its proposed size plus 2 GiB of free disk space. Other keys, comments and original encoding are preserved. Ambiguous configuration or a change since review is preserved and reported. No WSL environment is stopped.

If the active Linux allocation is still smaller, setup requests a Windows restart through its normal continuation flow. It detects a changed Linux boot and reports an unapplied configuration instead of requesting repeated restarts. The runtime checks current memory again before CFD starts. Automatic MPI count is a conservative scheduling heuristic; large meshes can still need more RAM. Mesh quality, time controls and solver tolerances are not reduced automatically.

Progress, cancellation and restart

The window shows each operation, recent output and elapsed time. Downloads, unpacking and first runtime imports can take tens of minutes; this is not an ETA. Windows-support status checks have bounded waits. Component transactions may need to reach a safe boundary after cancellation; the UI acknowledges the request immediately and explains that wait.

A required Windows feature or resource-allocation restart saves continuation. The bold next-action message and Restart computer confirmation explain how to reopen setup. Automatic reopening is attempted at the next sign-in when Windows permits its startup entry; installation still needs your acknowledgement.

Setup attempts to reopen after Windows sign-in. If it does not, double-click INSTALL-WINDOWS.cmd after the restart. Then select the acknowledgement and click the enabled install/repair button.

If setup says another window is open, reopening INSTALL-WINDOWS.cmd or UNINSTALL-WINDOWS.cmd tries to bring that verified window forward. It does not kill processes or reset WSL.

Every attempt has a new log headed by attempt ID, start time and source tree. Older messages in retained logs do not establish failure of the current attempt. Keep the current-attempt log when reporting an error.

Update or repair

Finish active work and use Close application before an update. Open INSTALL-WINDOWS.cmd, review Installed components, select the acknowledgement, then choose Install update / repair (or Continue / repair for unfinished setup). Compatible requirements are reused. A responsive older app may be closed only after the user approves its normal authenticated close request. Setup waits for shutdown and keeps saved work; it does not silently force-stop it.

If installation succeeded but opening failed, Open installed app retries that final startup step. Open existing app is also available for any verified installed build, including after an unexpected laptop restart. It opens that installed version; use Install update / repair for new application features. An error about an earlier build usually means its local service remains open even though its window was closed. Use normal app closure first. Open INSTALL-WINDOWS.cmd and choose Startup diagnostics for read-only registration and service checks. Copy the output if support is needed. It saves no report and does not start a Linux environment. A pending shared-service stop skips further WSL probes. WslService Running with OpenNAOE-HullCFD Stopped is normal before the application starts; it is not an instruction to reinstall or delete Linux.

A restart can leave an old application address that no longer answers. The launcher authenticates that address first, then permits reopening through the verified private engine's exclusive workspace locks. It never closes an unknown service. If another application instance owns the workspace, reopening reports that conflict and retains the saved files. Once open, use Solve → Recover interrupted case → Check complete saved writes to review continuation. Nothing resumes simulation automatically.

Diagnostics reads status; it does not stop an engine or repair shared Windows support. If Windows itself remains stuck, save other work before restarting Windows. Deleting a Linux disk is not a startup repair.

Uninstall choices and data scope

Open UNINSTALL-WINDOWS.cmd to review exact targets. The two options are:

• Remove launch icons only: remove Desktop/Start menu icons and setup continuation, keeping application files, engines and saved work.
• Full uninstall: remove every listed verified private Hull Resistance CFD engine, its Python/OpenFOAM/MPI and all projects/outputs inside it, plus verified app packages. Uncertain files and environments remain; a maintenance package may remain while an uncertain engine record exists.

Full-engine backup/export starts on. The deletion confirmation starts blank. At To confirm uninstall, type DELETE OpenNAOE: enter DELETE OpenNAOE exactly. Read the target names and export destination before confirming. Disabling backup means those engine files will be irreversibly lost if unregister succeeds. An export is not a guarantee of recovery unless it completed and was verified. Personal/uncertain distributions and shared Windows support are kept.

Ownership checks are repeated before removing a private engine. Uncertain or changed ownership blocks removal and retains that environment. The uninstaller does not automatically reset shared WSL or delete personal environments.

If internet access is interrupted

Setup reports that a required download could not complete and asks you to check your connection, proxy or firewall and retry. It retains completed components and resumable download data. Click Retry setup, or reopen INSTALL-WINDOWS.cmd and choose Continue / repair. No Linux uninstall is needed for this error.

If downloads are blocked by workplace policy, ask IT about the blocked download rather than disabling Windows protections. A fully cached compatible setup can reuse those components; setup does not require an unrelated website to be reachable.

Using the application

The application prepares immutable cases, runs the shared OpenFOAM v2412 workflow, and analyses retained results. The numerical setup follows the recipe of the command-line pipeline used for the archived validation runs. The author has installed and run release 1.0.0 on a clean Windows computer, and he runs the tool natively on Ubuntu 22.04 with OpenFOAM v2412; RELEASE.json lists these as his statements. A user's own hull case needs its own checks of mesh, time step and convergence. See Using the results for interpretation limits. For installation, see Installation, repair and removal.

Preview and local launch

Open gui/demo.html to inspect the interface offline. It contains no solver, mesh calculation or invented resistance results and makes no network requests. The preview cannot mesh or solve cases.

To run the application from the extracted folder instead of installing it, with Python 3.12 and the locked dependencies:

bash setup-linux.sh
sh launch-gui.sh

bash start-linux.sh enables native execution after checking a known OpenFOAM v2412 runtime. Preparation-only mode remains available when execution is off. The installed HullCFD Windows shortcut opens an Edge app window. It is the same local interface, without normal browser tabs; an ordinary browser is offered if needed. The title banner and menu stay visible while the workspace scrolls. On the first page, Hull, a short description of the tool sits between them and scrolls away under the banner. On small windows, scroll the menu sideways to reach further tabs. Changing tabs reveals the new section below the pinned banner and menu.

The button at the left end of the menu shows or hides the contents: the tabs and the sections each one shows now. From 720 px wide it stands beside the page, and its width can be set by dragging its edge, with the arrow keys there or with its two buttons; narrower, it opens over the page. The Dark theme switch at the right end of the menu shows the page dark or light whatever the system's setting; this browser remembers the choice until it matches the system's again. Verify the download, in the footer, says how to check a downloaded package against its published SHA-256.

Prepare a hull and conditions

Import STL or OBJ. Uploads accept files up to 64 MiB as a streamed binary body; large geometry is reduced for display only. The complete upload remains the solver input. Inspect units, bow direction, draught, reference length and scale. The Hull preview keeps the file's coordinates and marks the declared bow end. Condition turns the declared bow towards +x, matching the solver direction, while retaining model heights for the entered draught. The generated solver case shifts the waterplane to z = 0. The analytic Wigley example has identical bow and stern shapes; its selected direction is a declaration. Use 1 : 1 for a file already at simulation size; 1 : 10 divides its metre dimensions by ten. Enter draught and reference length at that reduced size. This does not extrapolate results to a full-size ship.

The current resistance recipe uses a fixed hull and centreplane symmetry. Supply a centreplane-symmetric full hull or its closed port half, with the keel at z = 0. An asymmetric hull, moving attitude or unsupported boundary configuration needs a separately verified setup; the import checks do not establish that validity.

Condition shows a second hull preview with the selected waterplane at model z = draught, or the draught solved from displaced volume. Before meshing, review computed volume, wetted area, waterline length/beam, hull depth and freeboard. Draught near the top triggers a warning; a plane outside the hull is rejected. The Hull tab itself shows no assumed waterline. The source convention requires keel z=0; with a declared reference length its forward origin is x=0 after the chosen bow transform. A hull outside the generated domain is rejected before meshing; geometry checks never move the source file silently.

The Campaign fresh water · 15 °C preset uses rho = 999.1 kg/m³ and nu = 1.13902e-6 m²/s, the values of the archived validation runs. The temperature-dependent fresh and sea water choices of the current ITTC procedure are labelled separately and record their method and source with the inputs. Keep the campaign values for a run that is to be compared with the archived runs.

Enter one or more speeds as Fn or m/s. Each receives its own saved case; the complete sweep maximum sizes the domain for every case. Cases are ordered by speed within the latest/earlier preparation groups. Readable names are labels; immutable IDs and hashes remain the authority for saved work.

Mesh, then solve

Fine uses the reference fine-fs-coarse recipe. Extra fine refines hull and wave resolution for sensitivity checks and costs more memory/time. It is not a separately benchmarked recipe. Coarse geometry check cannot proceed to a solve. The reference recipe includes the waterline collar, free-surface refinement, damping, mesh gates and one permitted remesh retry. Review warnings and actual mesh quality rather than judging only the 3D picture. Pre-mesh y+ is an estimate and has a known low bias; measured hull y+ is shown when a solve has produced it. Neither a coloured image nor a completed mesh utility establishes an acceptable solution.

MPI process count means the number of parallel solver processes. Automatic uses available Linux RAM, physical cores and CPU limits; Windows launches also report installed RAM and the shared WSL allocation. Manual accepts an explicit count. Automatic selection allows 2 GiB per worker plus the greater of 1 GiB or 10% RAM as headroom, capped by available physical cores. This is a scheduling rule, not a prediction of a mesh's peak demand. The count is frozen when cases are prepared; solver edits and continuation retain it. Recorded cell/memory examples are guidance, not a prediction for an arbitrary hull or a promise that the workstation has enough memory. The resource panel warns explicitly below the recorded 7.3 GB solve reference (about 6.8 GiB). A larger machine still needs its own mesh/resource assessment.

After an accepted mesh, open the case's solve settings. Defaults are 60 s, field output every 1 s, and the final 50% averaging window. The reference low-speed KCS Fn 0.108 run used 90 s. A warning appears below 10.6 flow-through lengths (end_time * U / Lpp); it does not replace convergence assessment. Fixed attitude and time-accurate interFoam/kOmegaSST are the supported GUI scope. Damping is enabled; stabilized turbulence is disabled.

Build mesh and Solve each list the cases with stage-specific status and show the selected case's own logs. Active execution logs expand automatically. Wall duration uses hh:mm:ss; simulated time and deltaT use seconds. Remaining wall time is projected only after measured simulation progress is available. Queued meshing never starts a solve automatically.

Stop, continue, save and reopen

When a solve is killed

SIGKILL means a process was forcibly stopped. It does not identify the sender. The failure panel distinguishes observed Linux OOM-kill activity, an explicit allocation error and an unexplained kill. It records Linux/WSL memory and swap before each command and samples available memory once per second. These are shared Linux resources, not the solver's own RSS or total Windows RAM; a short memory peak can fall between samples. Older attempts retain their original evidence and explicitly show missing historical measurements.

Review What to do before retrying, then Save diagnostics. Free memory and check the WSL budget before another run. More MPI workers on one computer share the same RAM and add overhead. Trying fewer workers may help but is not guaranteed; in this app it requires a newly prepared case and mesh. A Fine mesh that exceeds available RAM needs a larger machine or cluster, or an explicitly revised mesh with fresh acceptance and convergence checks. Coarse geometry check does not qualify a resistance solve. Changing end time does not cure a startup memory failure; short-run warnings concern the physical run budget.

WSL's memory and swap settings apply across WSL2 environments. The installer's selected Optimize WSL RAM and swap automatically option computes a plan from detected hardware, backs up an existing configuration and preserves other settings and higher explicit limits. Review the plan before installing. Setup offers a Windows restart if the allocation is not active; save work in every WSL application first. It never force-stops other environments. The runtime blocks a new CFD stage while a detected allocation change awaits activation, or when current RAM headroom is very low. Saved work remains accessible. See Microsoft's WSL configuration guide and OpenFOAM's parallel guide.

Copy shown log copies the displayed excerpt. Selecting log text pauses its refresh until selection clears; an unchanged completed log is not replaced on each status poll. Save diagnostics downloads the selected case/stage's log excerpt, recorded command evidence and a separately labelled current memory snapshot. It does not run or retry the solver. Keep the full saved solver log when reporting a failure.

Stop and recover

Saving is automatic. The saved field interval is measured in simulated seconds. For example, 0.05 s saves flow states at 0.05, 0.10, 0.15 s and so on. The fixed-hull preset retains the latest five scheduled saves per solver segment; older scheduled time directories are removed. These contain the flow fields needed to continue, independently of resistance analysis and its 100-sample gate. The native launcher checks that the actual controlDict uses this case's saved interval and end time before starting the solver. A recorded save schedule is not itself proof that a later write completed.

Open solver files in Solve opens the actual execution case. For parallel runs, look inside processor0, processor1, etc., then a numbered time folder such as 0.25. Files such as U, p_rgh, alpha.water and saved old-time fields such as alpha.water_0 are OpenFOAM data without filename extensions. CSV resistance histories and reports are created separately by analysis.

The named workspace/cases/<name>/settings-v1 folder is a browsing index. Its Inputs, Mesh and Solve links may appear as small files in Windows Explorer. They are not the flow data. Case-files.txt explains every item and gives the actual solver path when available, including while solving. Solver-files.txt is added when a stopped solve is published. Solve links may be absent during an active run; Open solver files still opens that attempt directly. These guides give the Linux and, when available, Windows Explorer path. The UI's folder action also offers a copyable path if Explorer does not open. Do not move or edit live data.

At a 0.05 s interval, a fresh run that reaches 0.45 s normally retains scheduled times 0.25, 0.3, 0.35, 0.4 and 0.45; its earlier scheduled full-field writes can have been purged. Initialization or copied checkpoint directories may also be present. This retention does not purge force/residual histories under postProcessing. A field time removed by retention cannot be recreated from those histories. The interface has no option to retain all field times. The save interval is physical-time output frequency, not the adaptive numerical step; shortening it increases write frequency and reduces the physical span of the five retained scheduled saves.

case.hullcfd is a project document, case.json describes case identity/settings, and *-status.json records the state at a Save action. None contains the volume fields. A cancelled status in an old saved JSON is historical; use Solve for the current attempt. .hullcfd-folder.json is application-owned browsing metadata. Inputs, Mesh, Mesh-<id>, Solve, Solve-<id> and Analyses are links, while Results-<id> contains the selected analysis exports when Save results was used. The attempt suffix is an identifier, not a time.

In the actual solver case, constant holds mesh/material data and system holds numerical controls. Serial <time> or parallel processorN/<time> directories contain fields such as velocity U, pressure p/p_rgh, water fraction alpha.water, turbulence and required restart fields. The native recipe writes binary fields, usually without extensions. postProcessing/forces contains force history; solverInfo residuals, yPlus wall units and freeSurface/<time> written interface/hull VTPs are separate products when available. VTP output is requested at a segment's end; private viewing can generate surfaces from a complete retained field time earlier in a run.

After an unexpected shutdown, the newest write may be incomplete. Reopen the app, recover the interrupted case when offered, then check complete saved writes. Verification uses the latest complete write shared by every processor and retains partial later files in the original attempt. Old-time fields use their original field's class and dimensions; their _0 suffix is not a reason to discard the write. The solver's uniform/cumulativeContErr is normal continuity-error bookkeeping. It is checked as a dimensionless scalar and carried into the continuation along with the flow fields and saved time. Do not delete it to bypass verification. Reopening never starts the solver automatically. Progress since the last complete save can be lost; an interrupted write is never treated as a complete state.

Pause the queue to prevent the next queued job from starting. Stop requests cancellation of the selected active job. Saved preparation, accepted mesh and completed outputs remain. The case's Continue action in Solve opens a compact dialog only when needed. It requires the same accepted mesh and a complete saved write and creates a new immutable solver version. Incomplete trailing writes remain in the old version; they are not copied into the continuation. It does not promise a checkpoint at the instant Stop was clicked. The confirmation explains this before stopping.

Before stopping a solve, a read-only check counts force samples in the same averaging window used by resistance analysis. Fewer than 100 samples produces a bold confirmation such as Stop with only 69 / 100 averaging samples? Choose Keep running to collect more, or explicitly confirm Stop case. If the count cannot be checked quickly, the confirmation says so and still offers Stop. These are raw force-history samples, not saved 3D field times; 100 samples is the minimum analysis gate, not proof of physical convergence.

A saved-write verification timeout means verification pending. It does not prove that earlier saved fields are missing. Keep the case and choose Continue saved solution → Check complete saved writes. After confirmed process termination, the check can verify an earlier complete write even if the stop-time field fingerprint was not completed. It preserves the original files and never bypasses a changed, previously recorded fingerprint. When a field is invalid, the diagnostic identifies its path and reason. For example, a complete 0.25 s write can be used while an incomplete 0.256 s write is retained only in the old version. To keep a 2 s target, add 1.75 s and retain the 0.05 s field interval. No solve starts until you explicitly continue.

Saving solver settings offers Update the current case or Create a new case using this mesh. Updating keeps the visible case name and accepted mesh, and preserves an immutable settings version; older settings, executions and analyses remain available in Results and 3D view. Saving alone never starts a solve. Start fresh solve is available in the case actions after saving.

The saved target and output interval are shown for the selected immutable case version. A 2 s end time must be saved in Solver settings before that version is started. Save run status records existing state; it does not apply an unsaved solver edit. A previously started 60 s version remains a 60 s version.

Default workspace and stage saves

The top bar contains Save project file, Open project file and Project file location. Stage saves sit in their own tabs: setup in Condition, mesh settings in Mesh setup, mesh in Build mesh, solver settings and run status in Solve, and results in Results. Saving uses the default managed location and requests File Explorer to open the folder. Explorer failure does not undo a successful save; a compact path-copy dialog is available instead.

Live cases run inside the designated Linux workspace. Choosing a different live workspace, such as a Windows Desktop folder, is not supported by this installer. For each prepared case, workspace/cases/<case name>/settings-v1/ and subsequent settings-version folders make its saved inputs, accepted mesh, stopped solve and analyses accessible together. These are browsing folders for retained managed data; do not move or edit live case data through them. The case data themselves and older settings versions stay where the application keeps them.

Meshes, logs and completed field writes are saved by their workers. Save mesh and Save run status record that saved state without rerunning or copying a large mesh. Save results writes report/history/CSV copies for the selected analysis. Save project file saves OpenNAOE-HullCFD.hullcfd in the workspace. You may copy project files and exported results to Desktop or other folders, but a project file is a reference to its original workspace, not a portable CFD backup.

Remove case appears in every recent/earlier row in both Build mesh and Solve, as well as in the selected-case panel. It hides all versions from the main lists without deleting files. Under Removed from workspace, choose Restore case to use it again or Delete permanently to erase its saved versions, mesh, solve files, analyses, named folder and the display caches recorded for it. Permanent deletion requires confirmation and cannot be undone. Shared preparation/source geometry, deletion records, exported copies elsewhere and older display caches not recorded for the case are retained. Active or uncertain operations must be stopped/recovered. Another case using its mesh or saved solution blocks deletion; delete that dependent case first, or keep the source. Interrupted cleanup offers Finish deleting and cannot be restored.

After a Windows update, power loss or unexpected closure, reopen the application. Pending work stays paused. Select the case in Solve, then choose Recover interrupted case when offered. Recovery first proves that its old simulation processes have stopped; it does not start CFD. Choose Check complete saved writes to inspect the saved fields. If no complete positive-time write exists, start a fresh solve using the accepted mesh instead.

For a verified write, enter Add physical simulation time. A saved 2 s write plus 3 s gives a new end time of 5 s. Review Save continued fields every; the interval must divide the new end time. Click Continue from … to … to preserve the original version and queue its continuation. If a later write was incomplete, confirm use of the earlier complete write; the original files remain available in the earlier version. If a prepared continuation was paused by another restart, Resume saved continuation uses its recorded starting state instead of fresh initial conditions.

The field check parses required ASCII/binary fields and saved timestep information against each rank's mesh, requires the same complete time on every expected MPI process and fingerprints the selected state. A fingerprint recorded when the solver exited must still match. After an unexpected restart, or for an older finished case without that record, explicit verification can establish the currently saved complete state after proving process absence. This does not establish what bytes existed before the crash or an older run's completion. A fingerprint that differs from the one recorded earlier, uncertain process ownership or invalid fields block continuation and retain the outputs. Large saved states can take time to check. Interactive verification has a 150-second limit; if storage throughput or saved-history size exceeds that limit, it reports the limitation and keeps the case stopped.

A .hullcfd project file points to a workspace; it is not a full backup of its meshes and fields. Keep that workspace when moving the project. Use result and cluster exports for the relevant files. Close application stops the local service and requests worker cancellation. If work is active, a confirmation explains its impact and defaults to keeping it running. Closing only the window leaves the service/background work running. Reopening reconnects to the retained workspace. A live workspace owner or uncertain simulation process blocks replacement work.

View and analyse

A bold label beside the 3D canvas identifies the loaded case/version, saved patch/type and, for results, its field and physical time. Selection changes and failed loads clear the old picture. Results charts likewise identify the loaded analysis. The analytic Wigley example has a rectangular centreplane side profile (flat keel and vertical end stems); inspect hull (wall) for its curved hull. This shape observation does not establish volume-mesh quality.

The case selectors use exactly the names shown in Solve. Each case appears once; Settings separately selects an earlier saved settings version. In Results, Latest solve · available results shows the current attempt's available force samples. Show also offers retained saved analyses. Their source solve status is labelled separately from the current solve, so an old cancelled analysis cannot describe a newer running attempt. Open results folder opens the selected saved analysis location. Save results writes copies in its named case folder and opens that folder. Managed result records should remain unchanged; use exported copies for other work.

Each analysis folder contains its summary, history, report and analysis record. The report, the run and analysis records, the configuration and project files the application writes and a printed page state the tool's scope, as in Using the results; the CSV files hold data only. A file saved earlier keeps the text it was saved with. Export CSV, Export full history, Export report and Reproduction bundle download the selected analysis through your browser. The browser's download settings determine the destination. Selecting a different case or analysis changes which result is saved, opened and exported. An offline HTML preview does not create or save CFD analyses.

Drag to rotate, scroll to zoom, and Shift/right-drag to pan. Fit resets the view. The saved domain plots show the actual waterplane section and centreplane profile with a common x range, direction and metres-per-pixel scale. Bow is towards case +x; flow is towards −x. A missing section is labelled rather than replaced by a generic hull. The saved-mesh viewer reads the selected boundary faces and coordinates directly from native ASCII or binary OpenFOAM mesh files. For parallel meshes it combines the selected faces from processor*/constant/polyMesh for display. It does not load all volume cells into a converter or need a reconstructed global mesh for this path. Compressed mesh files are supported. Display budgets remain explicit: an oversized patch gives an error without silently dropping faces. A saved mesh without these native face files is converted for display instead, on a private copy that leaves the original files unchanged. Mesh acceptance and the solver's own reconstruction outcome remain separate. The viewer identifies actual patch names/types and reports a mesh without a saved hull boundary; a box mesh is not shown as an accepted hull mesh. If WebGL fails, a bounded software view is used and identified. If a saved mesh polygon cannot be projected safely as a filled face, mesh inspection shows every saved face perimeter as a labelled wireframe. Filled field views retain their triangulation checks; no face is silently dropped. For a nonplanar saved polygon whose dominant projection collapses an edge, the filled viewer tries bounded oblique projections. It preserves the original 3D vertices, boundary order and scalar and checks each projection for intersections.

Saved interface and hullSurface VTP outputs provide free-surface elevation (coloured by z), hull pressure, velocity magnitude, water fraction and y+ when the respective fields were saved. Those surfaces do not require foamToVTK. The reader supports the actual v2412 binary connectivity framing, with strict offset-derived array lengths. Optional conversion supplies other saved boundary fields. The viewer identifies case, time, field, units and diagnostic status; volume slicing and streamlines are unavailable.

Choose 3D hull + free surface in Display for a combined view. Under Saved time, the mesh option shows the saved hull boundary with a flat, transparent still-water reference plane at z = 0. Result times include both written surfaces and candidate saved-field times. If separate surfaces were not written, Load surface verifies the selected complete positive-time write and generates the hull and water-fraction 0.5 interface in a private display copy. Serial and parallel saved fields use this same path for supported imported hulls and the example. No simulation is advanced and original saved fields remain unchanged. An incomplete write must be replaced by an earlier complete selection; a time with no 0.5 interface cannot show a free surface. The hull is grey and the transparent free surface is coloured by saved wave elevation; a missing result surface is never replaced with a flat plane. Both component reads must succeed before anything is displayed. Cancelling or changing the case, time or attempt clears the combined display.

Complete saved contours are available during a solve as well as after it stops. Private generation verifies and copies the selected save. It may share only that identified running solve's native slot; it never advances the solver or changes its files. New mesh/solve stages wait until the display utility exits. Concurrent generation requires available RAM above a conservative scheduling estimate of six times the selected saved-field bytes, with a 1 GiB minimum. This is a display headroom heuristic, not a solver memory prediction. If headroom is unavailable, written contours still work; stop and inspect the same save without a fresh run.

Results show available instantaneous resistance and coefficient samples from the first complete force record, with explicit transient and reliability warnings. They are not time-averaged resistance. For stopped, failed, interrupted or external output, a saved analysis is provisional automatically. Short records with at least two distinct force times can produce provisional means; fewer than 100 averaging samples cannot pass force convergence or show a batch-means confidence interval. Reliability warnings remain visible. The 3D viewer works independently of force analysis and sample count, using complete saved field times. It cannot display progress after the latest complete save.

Solve includes live signed-force and residual plots for the selected case and attempt, including after stopping or reopening. The controls remain visible while waiting for samples. Residuals come from existing solverInfo output or, for older runs, complete timestep records in log.interFoam. The log fallback uses each field's first initial and last final residual per completed timestep; it does not invent residuals when neither source saved them. Residuals have initial/final selection and a logarithmic default. These plots and the saved coefficient history support rectangle zoom, Shift-drag pan, Ctrl-scroll, explicit axis limits, linear/logarithmic scaling, series selection and Reset / follow data. User-selected axes survive live updates; changing the solver attempt resets them. A saved coefficient plot initially fits its Analysis interval, so startup spikes do not compress the three later curves against zero. Full history / follow data restores every available sample, including startup; Analysis interval returns to the analysed time window. This changes only the displayed axes. The tiles remain interval averages, the curves show instantaneous coefficients on the same ×10³ scale, and saved values, exports and statistics are unchanged. The plot reports larger extremes outside the displayed interval.

Legends appear inside the plots, with a matching solid, dashed or dotted line sample beside each variable. Click a multi-series legend entry to show or hide that curve. A single force series has a plain legend without a selection box. Axes and scale → Legend position moves the legend to another plot corner. Zero values are omitted and disclosed on logarithmic axes. Small residuals alone do not establish converged or accurate resistance.

Existing output needs no fresh CFD run after an update or repair. After a complete field save, stop and close the application before updating or repairing it, then reopen the same workspace. Continue the saved solution when more simulation time is needed. An already open older application continues to serve its older interface until it is closed and relaunched.

Mirror across centreplane reflects a half-hull, or both hull and water in the combined view, across y = 0. It changes only the display and retains the saved scalar values and colour range. It is unavailable for geometry that already spans both sides. The loaded-view label identifies a mirrored display.

In 3D view, What this view shows follows the display, saved time, patch and field selections immediately, then describes the loaded data and colour range. Boundary mesh, domain boundaries, boundary contours, the α = 0.5 interface and the combined hull/water scene each receive their relevant explanation. The field colour scale appears inside the viewport, with the quantity, units and minimum/midpoint/maximum. Legend position moves it between corners. Mesh inspection has no scalar colour legend; combined results colour the water by elevation and show the hull in grey. Mirroring retains the original scalar range. These controls apply to saved surfaces from any supported hull; they do not validate a particular hull or its CFD solution.

Large result surfaces are reduced for display and labelled approximate. The original files, source bounds, scalar range and source face count remain intact. Small features and topology can change in this view; it is unsuitable for mesh quality assessment. The exact boundary-mesh view keeps its separate size limit.

Results use C_T, C_Fv (wall shear), C_P, C_F (ITTC-57) and C_T − (1 + k) C_F, named the residuary-resistance coefficient C_R when k = 0 and the form-factor (ITTC-1978) estimate of C_W when k is the hull's form factor; the solver does not resolve wave resistance as a separate component. The exported CSV keeps this value in its C_R_pred column, with k in form_factor. Coefficient tiles are ×10³; resistance is N; the C_T tile includes its 95% confidence interval where available. New averaging creates a new analysis record. Failed/stopped/imported output is explicitly diagnostic until its provenance and completion requirements are satisfied. Exports retain the original inputs and histories needed to reproduce an analysis.

Export cluster case contains the prepared case, scripts and submission instructions. Returned postProcessing data pass bounded archive and run-record checks before shared analysis. An import does not create evidence that the local solver succeeded or establish what configuration was executed remotely. Imported results remain diagnostic. The exported ZIP includes instructions for meshing, solving and packing results on the cluster.

The Verification and validation tab gives statistics from the current reanalysis of 20 historical force archives and rounded per-hull aggregates of differences from cited experiments. Full measured tables and per-speed differences are withheld. Reanalysing historical forces does not validate a new GUI-prepared mesh, solve or installation.

Security of the local server, and what the tests show

The server binds only to 127.0.0.1, authenticates with a per-launch token and checks Host/Origin. Mutations require the intended content type; the binary upload route is separately bounded. There is no arbitrary command or filesystem endpoint. Private workspace creation, immutable inputs, scoped IDs and idempotent requests guard stale tabs and duplicate submission. Transfers check free disk space before receiving and allow one receive at a time. The same returned contents for an export cannot be imported twice, even if its ZIP comment, ordering or compression changes. Damaged older import records are retained and do not block different results. Returned ZIPs support stored or deflate compression. These checks run before a transfer; they are not a storage quota. New transfer and capture staging is private regardless of a permissive umask. Abandoned reserved staging is cleaned conservatively at startup and never displayed as a completed execution; uncertain existing storage is retained.

The shipped analytic Wigley example is original CC0 geometry generated by the project's double-parabolic Wigley generator (L=10 m, B=1 m, T=0.625 m). Its exact bytes alone receive the declared orientation exception for a fore/aft symmetric hull; other files retain the orientation check regardless of their name, unless the user explicitly selects Use my declared bow direction without the automatic geometry check. This uses the prediction engine's option for symmetric barges, double-ended and unconventional hulls. The choice is saved with the input and recorded as a warning; it resets when a new file is loaded. It does not bypass watertightness, coordinates, hydrostatics, mesh or y+ checks.

The tool's automated tests, with synthetic process fixtures and browser checks, establish software behaviour. They do not establish Windows compatibility or CFD accuracy. See Using the results for interpretation limits.