Principles for Use

1. Program Modules

The program is divided into 3 separate modules:

STAMOD: initial condition and static equilibrium
DYNMOD: dynamic response calculation
S2XMOD: export of time series to various file formats

2. Interactive Communication

The program is basically an interactive program, but can also be run in batch mode. The input from the terminal can be divided into five types:

Selection among a number of options that are presented on the screen.
Giving parameters to a command.
Giving text strings for identification.
Yes/no answers.
Waiting on user response.

Common to all types of input is that they allow definition of a macro file, they allow a macro file to be executed and they allow temporary switching of control to the operating system.

The program uses MAIS - MArintek Input System for handling the interactive communication. This system is described in appendix B. Useful features of this system are :

Numerical values have default values and allowable range. Range check can be deactivated by 'range off'.
Lower-case and upper-case letters are accepted as input.
The program will never stop because of wrong input.
Switch commands (print, file) may be given anywhere.
User input may be logged on a macro file for documentation or later input.

3. Macro System

Macro system commands (starting with @) can be used anywhere where the program waits for input. The commands must contain enough characters so that they are unique. When the user writes @ HELP a short description is written at the terminal.

The following macro commands are available:

@ HELP - Writes a list of all macro system commands.
@ CREATE filename or @ OPEN filename - The command opens a macro file for writing. All questions and answers until `@ CLOSE' is given will be stored on the macro file. If the command is given a second time before `@ CLOSE', `@ DO filename' is stored on the macro file.
@ CLOSE - The command closes the macro file which is opened for writing.
@ DO filename * - Input is read from the specified file. The file is read *n times, n may be omitted.
@ LIST filename - The contents of the file are listed at the terminal.
@ SPAWN or @ PAUSE - The program is set in a "waiting condition". A new process is created. This means that all operating system commands can be given.
@ WAIT ON/OFF - Changes the program switch IWAIT to 1/0 respectively. This switch is used internally in the program to check whether `press return to continue' shall be written on the terminal
@ DISPLAY ON/OFF - Changes the program switch IDISP to 1/0 respectively. This switch is used by the program to enable/supress output to the terminal.
@ RANGE ON/OFF - Changes the switch IRCK to 1/0 respectively.
- 1 ⇒ON (default) ⇒ Numerical input is checked to be within specified range.
@ BATCH ON/OFF - Changes the switch IBATCH to 1/0 respectively.
- 1⇒ ON (default) ⇒ Program behaves as a batch program. This means that it terminates if wrong input is given.
@ FILE ifile - Changes the program switch IFILE. Allowable range is 0-5. This switch can be used to change the behavior of the program.
@ RESULT iresu - Changes the program switch IRESU. Allowable range is 0-5. This switch can for example be used by the program to change the amount of printed information.
@ *IDENT * - Number of words in "identifying text" to be used. Allowable range is 0-5.
@ STATUS - Lists the values of the macro switches.
@ BACK - Backspace macro file.
@ MSG_F file - Set file for printing messages. `@ MSG_F close' will close file.
@ MSG message - Print message to file (defined by `MSG_F')
* - The parameter parameter that is currently read shall be read from terminal when a macro file is executed.

Assume that the user wants to undertake several batch runs. To prepare an input file, the user first runs the desired program and logs the terminal input on the file FILA.MAC. This is done by giving the command

@ open fila

This causes the file FILA.MAC to be opened. All input to the program that is given from terminal will be stored on this file. When this first run is finished, FILA.MAC may be duplicated and modified if wanted.

When the program waits at the same question where recording of the macro file started, the commands can be repeated by:

@ do fila

4. Selection of execution mode

Each SIMO program may be run in two different ways:

interactive mode.
batch mode.

Selection between interactive and batch mode is done within the modules. A symbolic file with name 'SIMO_DEF.DAT' is searched for at the default directory. The file should contain 3 lines with a character variable on each line:

CHMODE
CHSYS
CHINI

If the file is not found, the execution mode will be interactive, and both CHSYS and CHINI will be blank. Batch mode is selected only if CHMODE has the value >batch= or BATCH. CHSYS and CHINI are used for generation of default file names as explained in File system.

Batch mode is useful when several simulations shall be undertaken. The necessary input for running the program may be prepared with a text editor, but it is recommended that the user prepares the input "run-file" by running the program in demand mode and logging the input at a macro file. If necessary the macro file can be edited.

Batch mode and interactive mode are different only in the way they respond to detected errors in the program execution and the amount of output presented at standard output device (screen).

Details about running the program on different computers are found in the implementation and testing manual.

5. Units and physical constants

All input data must be given in a consistent set of SI units, which are defined as a part of the input data set.

	Property	Notation	Example
Basic units	Length	\(\mathrm {L}\)	\(\mathrm {m}\)
	Time	\(\mathrm {T}\)	\(\mathrm {s}\)
	Mass	\(\mathrm {M}\)	\(\mathrm {Mg=tonne}\)
Derived units	Force	\(\mathrm {F=ML/T^2}\)	\(\mathrm {Mgm/s^2=kN}\)
	Pressure	\(\mathrm {P=F/L^2}\)	\(\mathrm {kN/m^2=kPa}\)
	Velocity	\(\mathrm {V=L/T}\)	\(\mathrm {m/s}\)
	Acceleration	\(\mathrm {A=V/T}\)	\(\mathrm {m/s^2}\)

Property

Notation

Example

Basic units

Length

\(\mathrm {L}\)

\(\mathrm {m}\)

Time

\(\mathrm {T}\)

\(\mathrm {s}\)

Mass

\(\mathrm {M}\)

\(\mathrm {Mg=tonne}\)

Derived units

Force

\(\mathrm {F=ML/T^2}\)

\(\mathrm {Mgm/s^2=kN}\)

Pressure

\(\mathrm {P=F/L^2}\)

\(\mathrm {kN/m^2=kPa}\)

Velocity

\(\mathrm {V=L/T}\)

\(\mathrm {m/s}\)

Acceleration

\(\mathrm {A=V/T}\)

\(\mathrm {m/s^2}\)

Angles are given in degrees, \(\mathrm {[deg]}\), and coefficients which are multiplied with rotational state variables are given for rotations in radians. Angular velocity is given in radians per time unit, for instance \(\mathrm {[rad/s]}\). Thruster speed and rotation are given in revolutions per minute, \(\mathrm {[RPM]}\). Internally in the program, all angles and rotations are converted to radians.

6. Error Messages

An error is reported where it is detected. The string to be searched for on the print file is:

*** ERR

Error flags and messages are transferred towards the root of the call tree. In interactive mode, the user is given control at a high level and can decide whether to continue or terminate the program. In batch mode, the program is terminated at the top level.