GHS BULLETIN
User Variables and Variable Arithmetic
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° 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° to the lesser of 14° or angle of half freeboard.
This single limit as defined will cause GHS to set the system variable limmarg
to 14° 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
co
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.
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.
If you would like to see another bulletin created regarding a specific topic,
please email Creative Systems, Inc. at support@ghsport.com.
Copyright (C) 2011
Creative Systems, Inc.