User variables have been available in the GHS command language for some time. Typically used in macros and run files, user variables allow certain operations to be performed in the GHS environment. With user variables, values not normally used or directly computed by GHS can be determined, reported, used to check compliance with a stability requirement, or passed on as a parameter in other GHS commands.

In addition to user variables, GHS utilizes several system variables. System variables make the current value for certain internal variables available to the user. Such system variables include the fixed weight and center, total weight and center, some tank information, displaced volume and center of buoyancy, project name and origin description to name a few. A complete listing of system variables is in the user manual under the variables command. These variables can be accessed and implemented the same way as user variables. The only difference is that system variables do not need to be declared and their values are automatically updated by GHS.

The first step to using user variables is to declare each variable. Users familiar with basic programming practices will recognize the elements involved in a GHS declaration. A declaration is made with the variable command. When issued with parameters, the variable command defines the type of variable(s) being declared. Two types are acceptable, real or string. If a variable type is not specified, the default is real. Optionally, the minimum and maximum value to be allowed with each can be given. For real variables, the min/max values given are real numbers, for string variables, the min/max values given are the minimum and maximum number of characters the variable is allowed. For example, to declare a real variable called 'angle' that will always be between 0 and 90 inclusive, and a string variable name 'list' that will always be "PORT" or "STBD"...

variable (real) angle:0:90
variable (string) list:4:4

Multiple variables of the same type can be declared on the same line.

If the variable command is issued without parameters, a list of all the system and presently defined user variables appears with their current values.

A declared variable is undefined until a value is assigned to it. This is done with the set or input command. The set command will assign a value to the variable when the command is executed. The input command, typically executed in a run file, will prompt the user to enter a value from the keyboard.

To demonstrate the use of variables, the following commands can be used to have GHS check compliance with the US Coast Guard Weather Criterion (46 CFR 170.170). These commands can be executed as they appear below or be part of a run file that checks several intact stability criteria of the subject vessel. As for any computation involving wind heel moments, the lateral projected area must be part of the geometry and if the angle to half freeboard is suspected to be limiting, the deck edge must be marked by defining a margin line in PartMaker.

clear
read fvw.gf
draft 6
solve we lcg
vcg 12
variable (real) gmreq, gmact
variable (read) windmom, tanang
variable (string) wxsat:0:3

The above block of commands sets up the waterplane in question. This could also have been accomplished by giving a weight and center and adding tanks and fixed weight loads. The variables to be used are declared. gmreq and gmact will be used for the required GMt found in accordance with 46 CFR 170.170 and the actual GMt computed by GHS respectively. windmom will be the total wind moment based on the lateral projected area and pressure and tanang will be the tangent of the limiting angle, 14 deg. or the angle to half freeboard, whichever is less. wxsat will be used to display the results after gmreq was checked against gmact.

The following macros should be used if several stability criteria are being checked within a single run file. The first clears any existing limits then sets an angle limit from 0 deg. to the lesser of 14 deg. or angle of half freeboard. This single limit as defined will cause GHS to set the system variable limmarg to 14 deg. or the angle to half freeboard, whichever is less, whenever a righting arm calculation is performed and limits are evaluated.

macro 170170
limit off
limit title USCG Weather
limit angle from abs 0 to 14 or hf >0
/

macro 170calcs
set gmact={bmt} plus {vcb} sub {vcg}
wind (pressure) 0.005
`P=0.005+(L/14200)^2
hmmt wind /const
hmmt report
set windmom={hmmt}
hmmt off
rah /lim:at `notab
set tanang =tan {limmarg}
set gmreq={windmom} div {displ} div {tanang}
if {gmact} >={gmreq} then set wxsat="S" else set wxsat="Uns"
\\
\Actual GM = {gmact}
\46 CFR 170.170 Required GM = {gmreq}
\Weather Criterion found to be {wxsat}atisfactory
/

The above macro performs the steps necessary to check the criterion. This macro assumes weight and displacement equilibrium at the time the macro is invoked. The command,

set gmact={bmt} plus {vcb} sub {vcg}

sets the user variable, gmact, to the actual transverse GM using the system variables, BMt, VCB and VCG. When using variable arithmetic the space separator between operators is required. The curly brackets, { }, are used whenever a variable name is to be used. The only exception is the expression to the left of the equal sign in the set command and for the input command. The sole purpose of these two commands is to assign values to variables. Therefore GHS is expecting a valid variable name and the curly brackets are not required. The available operators are:

plus
add
minus
subtract
times
multiply
divide
power
sin
cos
tan
atan
abs
sqrt
trunc
left n
cap

The documentation for the set command in the user's manual describes each operator's function. Only the first two characters are significant for each. The order of execution is strictly from left to right.

If a user defined free surface moment is in effect, an additional variable will be needed to calculate the free surface correction and then this value will need to be subtracted from the above. Besides the declaration of a new variable, say fsa, the following line must be added.

set fsa={fsmmt} div {displ}

and then the calculation for gmact would be,

set gmact={bmt} plus {vcb} sub {vcg} sub {fsa}

The pressure commands sets the wind pressure to be used according to 46CFR 170.170(a). Be sure consistent units are used. Next the heeling moment due to wind is computed and reported for the current condition. The /const parameter causes the heeling moment calculated to be that at zero heel. The following set command takes the present value of the system variable hmmt, the current heeling moment, and assigns it to the user variable, windmom.

Finally, a righting arm calculation is executed so the system variable limmarg is set to the appropriate angle and the required GMt can be computed according to 46 CFR 170.170(a). Once the required GMt and actual GMt are known, these values can be compared with an if statement and the string variable wxsat set to report the results. Note that in the if command, the user variables in the condition statement are contained in brackets. Since these expressions are not always variable names, GHS needs to be signaled that variables are being used.

Once the above macros are incorporated into a run file, a line must be added to the run file to execute these macros, for example,

.170170
.170calcs

Getting GHS to evaluate the US Coast Guard Weather Criterion is just one possible use of user variables and variable arithmetic. By making use of the features in the note command and the operators available with the set command, it is possible to customize GHS to perform hydrostatic calculations for almost any situation.

  Back