User Guide - SHORTCUt CFD

Basics Installation Getting started Structure of a SHORTCUt case SHORTCUt commands The settingsDict Custom OpenFOAM solvers and library

Basics

SHORTCUt is a toolbox that provides a shortcut around the tedious work of setting up successful ship performance calculations in the open source CFD suite OpenFOAM. It also includes custom OpenFOAM libraries and solvers which greatly simplifies the task of accurately modeling self propulsion and propeller/hull-interaction.

This software is meant to be used together with an existing installation of OpenFOAM on a Unix-type system (Such as Ubuntu, CentOS etc.) Usage on Windows systems by emulating a Unix environment (through e.g. Docker or VirtualBox) is possible but not tested.

As with OpenFOAM, SHORTCUt has no user interface. User interaction is handled through:

Shell commands in a Unix terminal
Settings contained in text files

In contrast with OpenFOAM however, SHORTCUt has only a handful of shell commands and only one settings file. This replaces the dozens of settings files, in various folders, used by standard OpenFOAM.

Installation

Before installing SHORTCUt, make sure you have a working installation of OpenFOAM (compatible versions are indicated in the Downloads-page.) SHORTCut also requires gnuplot for plotting, averaging force histories and other post-processing tasks. gnuplot is shipped with most Linux operating systems.

SHORTCUt can be installed on any Unix-type system that supports shell scripting. It was written and tested in the bash shell. To install, run the provided install_all-script as follows:

bash install_all

The install_all script will do three things when executed:

Make a copy of all SHORTCUt files to a directory of your choice. (Default is OpenFOAM ThirdParty directory.)
Set custom file paths within the scripts to match your file system.
Compile the custom OpenFOAM libraries and utilities.

You can test the installation using the wHelp-command

Getting started

After successful installation, the command newShip will be used to create a new SHORTCUt case. The command should be followed by the name you wish you give the case folder. Or the full folder path. If only a name is provided, the case will be created in the current working directory.

newShip myship

newShip /home/myname/OpenFOAM/run/ships/myship

Structure of a SHORTCUt case

A SHORTCUt case is a folder created by executing the newShip-command. It is copied from a template and contains two sub-folders and the file containing all SHORTCUt settings.

settingsDict - This is the most important file in SHORTCUt. It contains all settings needed to conduct the simulations. No other files need to be modified.
doubleModel - This is the OpenFOAM case used for self propulsion calculations. If an estimate of Cw is not needed, this is the only case you will need to run.

Note: Self propulsion simulations are done as "double model" computations. When using the option to find the self propulsion point automatically is used, this is found by balancing the resistance and thrust (with model-ship correlation allowance.) This means that, for faster ships with a significant amount of wave making resistance, the required thrust (and RPM) will be underpredicted. This can be alleviated by manually adding the wave making resistance (calculated by VOF or other means) to the "towForce" variable in the propeller dictionary (propellerDict.) There is an option to do this automatically using the Cw variable in the settingsDict (See KCS tutorial.)
VOF - This is the multiphase OpenFOAM case used to estimate the wave-making resistance Cw.

All SHORTCUt commands must be executed in either the doubleModel or VOF sub-directories. They will read the settingsDict of the parent case directory to determine how to set up the simulation.

SHORTCUt commands

This is a list of all new commands available after installing SHORTCUt. All relevant output from these commands are stored in log files in the root case directory (where settingsDict is.) For example, information about mesh quality, coefficients of resistance and self propulsion parameters will be stored in doubleModel.log when running SHORTCUt commands in the doubleModel directory.

newShip <name> - Creates a new SHORTCUt case.
wAllmesh - Creates the mesh according to settingsDict.
wAllprep - Decomposes the case and sets the boundary conditions according to settingsDict. Also runs a potential flow initializer to speed up RANS convergence
wRtest - Runs a resistance test using simpleFoam(doubleModel) or interFoam(VOF). Calculates and reports the form factor and the coefficient of total resistance. If the simulation is in model scale, both the model scale and full scale Ct will be reported. The difference can be used later to find the ship self propulsion point using a model scale simulation.
wStest - Runs a self propulsion test using the custom solver selfPropsimpleFoam. The settingsDict contains many settings for controlling the propeller model, the RPM and the propeller geometry. For example, the RPM can be kept constant or set to vary to find the shipselfpropulsion point according to the model-ship correlation found from the resistance test. Calculates and reports the coefficient of total resistance and the final propeller rotation rate, thrust and torque.
wCoeffs - Performs a thrust identity calculation using the propeller open water performance (calculated using the chosen propeller model) to yield the wake fraction, thrust deduction, efficiency and other relevant parameters. Based on the output from wStest.

The last five commands, run in the order specified above in the doubleModel folder, concludes the ship performance calculation. SHORTCUt also comes with a few auxiliary commands, namely:

wPOT - Runs an open water test using the selected propeller model. Plots the result. If the current directory contains a file called expPOT.dat with 4 columns of experimental open water results (J Kt Kq η) and a header line these will also be plotted for comparison.
wProptest - Runs the selected propeller model using the flow situation in the given time step. This includes probing the inflow but not mapping the body force since no coupling is performed to the RANS simulation. This command can be used to test the propeller model since its behaviour will be identical to that it would have when running coupled.
forcePlotter - Custom plot function that combines force files written by OpenFOAM and plots them according to a system/forcePlotterDict file.

The settingsDict

The settingsDict (together with any stl files used) is the only file needed to define a calculation using SHORTCUt. This means that it can be shared and copied freely into any SHORTCUt root case folder to yield the same calculation. By default, the settingsDict given when the newShip-command is run describes a calculation for the Japan Bulk Carrier (JBC) benchmark case with a fine mesh. This is the same calculation that is showcased in the validation section (using the Yamazaki propeller model.) Other benchmark cases are available. The default settingsDict should be well commented to let the user know what each setting does. Many of the settings can be left unchanged from the default. However, some key ones that probably needs to be changed are listed below.

Global settings

localRun (true/false) - If this is set to false, SHORTCUt will not execute the main solvers. Instead it will do all the preparation work; then wait for the user to submit a calculation order to an HPC cluster.
stlPath (string) - Allows the user to specify a single directory to keep all CAD files in.

Common settings for both doubleModel and VOF

common/Fn (number) - Give the ship speed (Froude number) to conduct calculations at.
common/S (number) - Give the wetted surface area for calculating resistance coefficients.
common/simulationScaleProperties - Give the properties of the fluid to be used in the simulation.
common/fullScaleProperties - Give the properties of the fluid to be used when scaling to full scale (if the simulation is done in model scale.)
common/applySinkageAndTrim (true/false) - Give the hull forced (fixed) values of sinkage and trim.
common/sinkAndTrim - If the above is true, specify values of sinkage and trim.
common/propeller - Define the propeller geometry, control scheme and model.
common/Cf0Method (number) - Specify what friction line to use (default is ITTC1957.)

Settings for the propeller

This sub-dictionary contains the definition of the propeller geometry.

common/propeller/radius (number) - radius/Lpp
common/propeller/bossRatio (number) - boss radius/radius
common/propeller/position (vector) - Propeller location (xp yp zp)/Lpp relative to AP at waterline
common/propeller/rotDir (number) - Direction of rotation 1-> clockwise -1 -> counterclockwise
common/propeller/nBlades (number) - Number of blades
common/propeller/nRefRads (number) - Number of radii where reference data for the geometry will be given.
common/propeller/refRads (list) - List of radii where reference data for the geometry will be given.
common/propeller/pitchD (list) - Reference data for the geometry (list of P/D at refRads)
common/propeller/chordD (list) - Reference data for the geometry (list of C/D at refRads)
common/propeller/thickD (list) - Reference data for the geometry (list of T/C at refRads)

These should be changed to be representative of the propeller the user wants to use. common/propeller also specifies what model to use to represent this propeller and how to control the RPM.

common/propeller/modelName (string) - What propeller model to use?
- Yamazaki (default) - A hybrid lifting line/surface model able to accurately capture propeller/hull interaction.
- BEMt - A coupling of blade element and momentum theory able to capture propeller/hull interaction.
- templateModel - A simple actuator disk that uses a pre-defined distribution of thrust and torque and is able to capture a limited amount of propeller/hull interaction.
- Any other custom user-made model added to the propeller library.
common/propeller/controlType (string) - How shall the propeller RPM be controlled (default is to vary it to find the ship self propulsion point.) Other options are "constant" or "fixedVar". fixedVar varies the RPM to keep a certain variable (like Kt or Kq) constant.

Settings for the double model calculation

doubleModel/nProcs (number) - Number of cores to use. If this is >1, the case will be decomposed and solvers will be run in parallel. Make sure this is set to an appropriate number for your system.
doubleModel/stlName (string) - Name of stl-file to represent the hull. SHORTCUt will search for this stl in the following order:
- If stlName contains a full valid path to an stl, this will be used
- Otherwise, if it contains only the file name, it will search in the stlPath specified in settingsDict.
- If it is not found there, it will look in the OpenFOAM tutorials/geometry folder
- If neither of these options are a match there will be an error.
doubleModel/addAppendages (true/false) - Add separate stl-files as appendages.
doubleModel/appendages - Each sub-dictionary added here will add a new appendage.
doubleModel/stlScale (vector) - Give information about what scale the given stl files are in. This will be used to determine how to position the mesh around the stl.
doubleModel/stlWL (number) - In addition to stlScale, give the coordinate of the waterline in the given stl files.

Settings for the double model mesh

doubleModel/meshInfo/blockMesh/scale (number) - The basic setting to control the mesh density. By varying this parameter and keeping everything else constant, a mesh independence study can be achieved. E.g. 1 (fine), 2(medium, every cell dimension is multiplied by 2 compared to "fine"), 4(coarse, every cell dimension is multipled by 4 compared to "fine")
doubleModel/meshInfo/blockMesh/scaleyplus (true/false) - Specify if the prism layers should be exempt from being affected by the scale factor.
doubleModel/meshInfo/snappyHexMesh/thicknessValue (number) - Specify the y1+ (first prism layer thickness.)
doubleModel/meshInfo/snappyHexMesh/nLayers (number) - Number of prism layers to grow.
doubleModel/meshInfo/snappyHexMesh/expRatio (number) - Expansion ratio of prism layer growth.

Settings for the VOF calculation and mesh

These work similar to the double model settings.

Custom OpenFOAM solvers and library

SHORTCUt helps to set up the usage of the custom OpenFOAM utilities for propeller modeling. However, the self propulsion solver, utilities and propeller modeling library can also be used completely standalone after they have been compiled. This is useful for advanced users who want to make modifications to the propeller model, test different turbulence schemes, convection schemes or any other modifications that are not available through the SHORTCUt scripts.

When compiling the custom package (done automatically by the SHORTCUt install script) the following new OpenFOAM utilities will be available:

selfPropsimpleFoam - A modified version of the basic OpenFOAM SIMPLE solver simpleFoam. Calls the propeller library to determine the body force distribution and adds this to the momentum equation.
openWater - Runs an open water test with the specified propeller model.
propellerCalc -time <time> - Runs the selected propeller model using the flow situation in the given time step. This includes probing the inflow but not mapping the body force since no coupling is performed to the RANS simulation. This command can be used to test the propeller model since its behaviour will be identical to that it would have when running coupled.
libpropeller - All propeller models, propeller control schemes and other custom functionality used by the above commands are contained in the library libpropeller. Since they are not written directly into the solver, they are run-time selectable making the simulation modular. This is similar to how OpenFOAM handles selection of turbulence model, convection schemes and other run-time selectable options.

In addition to all the regular files required in an OpenFOAM case, the custom solvers use tow dictionaries to define the propeller and the hull. propellerDict and hullDict.

Table of contents