$Id: README,v 1.1 1995/04/07 02:35:35 bjax Exp bjax $

***** RELEASE NOTES for version 1.4d of LaRCsim *****

This BETA version of LaRCsim includes the following improvements/bugs:

  * Trim capability

  * Optional initial conditions selection flag

  * Greatly enhanced settings file capabilities

  * Variable time-step size & initialization flags passed to model routines

  * Simulation options remembered from run to run


QUICK SUMMARY OF CHANGES:

  v1.4d: Now remembering sim options; added flags to modify data
  	 buffer size at command line.

  v1.4c: Screen update selection flag '-o'; passing dt and init flags
         to model routines; sky darkens (in GL mode) as altitude
	 increases; module ls_ifsun renamed to ls_ifterm.

  v1.4b1: Settings file increased to include trim and init parameters.

  v1.4b: First v1.4; includes trim capability.


IMPACT ON VERSION 1.3 SIMULATIONS

The only impact on existing simulations is (1) a minor change to the
HUD display, and (2) the renaming of the settings file, described
below:

(1) The throttle percent display "T XX%" is now driven by the
global variable "cockpit_.throttle_pct" (macro definition of
Throttle_pct) instead of "cockpit_.throttle[3]" (macro name
Throttle[3]). This change was made to (1) support multi-engine
throttle aircraft and (2) provide a single throttle "hook" for the
TRIM routine (see below).  The simulation will still respond to
cockpit throttle changes; the modeler might wish to supply logic to
provide a value in this global variable to display throttle setting
once again.

(2) With this release, we are adopting the "dot" convention for hidden
resource files for UNIX applications. Thus, the settings file has
moved from "navion.set" to ".navion", where "navion" is a typical
simulation executable name.  If you don't wish to take immediate
advantage of trim and IC capabilities, simply rename the settings file
from "*.set" to ".*" (where * is the name of your executable sim).


NEW CAPABILITIES

Aside from the changes described above, there should be no impact to
the user-supplied models based due to these changes. However, to take
advantage of these new capabilities, the user might wish to perform
the following steps:

  == TRIM CAPABILITY ==

The 'T' key initiates an attempt to 'trim' the vehicle, based upon
user-supplied trim controls.  If it is unsuccessful, an error message
is printed on the stderr display (usually the underlying screen) and
the simulation continues (with a perhaps slightly perturbed flight
condition - this is a minor bug). If the trim IS successful, the
simulation will move the vehicle to the new trimmed state  and record
that state as the new initial condition, to which subsequent resets
will return.

Although full six DOF (and higher order) trims are possible,
longitudinal flight- and ground-trims only have been demonstrated.

The user must specify, in the "dot" file (see below), the set of
control variables and output variables the trim algorithm should use.
For a longitudinal flight-trim, a typical set of controls are pitch
attitude, a longitudinal trim actuator value, and throttle setting;
typical trim outputs (which the trim algorithm attempts to set to
zero) are pitch acceleration and body-axis X and Z accelerations.

Along with the trim controls, the user must specify min-max values and
a perturbation size. The user must specify a trim "criteria", or
boundary about zero, for each trim output. The trim algorithm
considers a trim successful if it can, by manipulation of the trim
controls, force the trim outputs to within each "criteria" of zero.

The trim controls and outputs are specified in the appropriate section
of the "dot", or resource, file (described below).

Utilization of this trim capability may impact user models, since
special behavior may be required on the part of the aircraft in
response to a trim request. For example, in a multi-engine simulation,
the "Throttle_pct" variable provides a scalar variable for the trim
routine to vary all engines; the user must recognize this and drive
the individual throttles using "Throttle_pct" global variable in trim
attempts. 

To provide this capability, all higher-level model routines (aero(),
engine(), inertias(), gear(), and subsystems() routines) are now
called with two additional parameters: dt and and initialize flag. The
trim routine calls these models with the initialize flag non-zero, and
the time step variable dt set to 0.0 .  The engine() routine should
respond to this condition by (1) bypassing all filters and (2) using
the Throttle_pct global variable to drive set all the engine
throttles. Similar measures will be necessary in complex control
systems.


  == IC SELECTION FLAG ==

A new run-time command switch, '-i <ic file name>', will read in an
optional initial conditions file.  The contents of this file, which is
user-supplied, can be user-specified values for simulation states.
More typically, however, a user would cull this information from the
"dot" file of simulation run in which a successful trim was performed,
since the "dot" file contains the last initial condition that was
successfully trimmed in a previous simulation session.

To make an initial conditions file, simply snip out of a "dot" file
the "init" section, and save it in another file with an appropriate
name (we recommend an ".ic" extension, but that isn't necessary).

Also, the model_init() routine should be shorn of all
aircraft-specific initializations. Under v1.3 and earlier, the
model_init routine was required to initialize all vehicle states.
These initializations should be moved to the "dot" file (see below).
Leaving them in place will interfere with command-line specification
of initial conditions.

In order to properly reset the simulation completely to a new flight
condition, any "init" section of a settings (either IC or "dot") file
should contain a complete list of all model states. By default, the
first 13 states of the rigid body airplane (plus the rotation angle of
the earth) are included. The user should include any aircraft specific
states, such as control surface positions (if driven by an actuator
model), landing gear position, and filter states.  Discrete (integer)
states are also supported to set mode flags.

  == SCREEN UPDATE RATE SELECTION FLAG ==

The "-o" option allows modification of the default screen update rate,
similar to the "-f" flag for model iteration rate. The mandatory
parameter to both of these flags is an iteration rate in Hertz, or
screens per second.  The model iteration rate should be a multiple of
the screen iteration rate. Default values are 20 Hz and 120 Hz,
respectively, for screen refresh and model iteration rates.

  == STORAGE BUFFER OPTIONS FLAGS ==

The '-b' flag allows the user to specify the number of seconds' worth
of data the circular storage buffer should be capable of saving before
the oldest data is lost. Normally this is set to the same length of
time as the end-of-run, but this may result in impossibly large data
files and/or loss of real-time execution capability if the end time is
large (and the data storage rate is fast, and many parameters are
being recorded).

The '-s' flag allows specification of the data storage rate, in frames
per second. This must be a sub-multiple of the frame rate: if the
execution (model rate) is 120 Hz, then '-s' may be 120 Hz (every
frame), 60 Hz (every other frame), 40 Hz (every third frame), etc.
This will allow storage, in relatively small files, of larger amounts
of run-time data.

The maximum number of data channels that can be stored has been
increased from 256 to 1024; and is now stored more efficiently.


  == ENHANCED SETTINGS FILE ==

The new "dot" file (typically ".navion"), which used to be a ".set"
settings file, is used to specify recorded parameters, trim controls &
states, and default initial conditions (at present).  At the end of
each simulation session, these parameters are written to the "dot"
file in a easy-to-read text format. At the beginning of each
simulation session, this file is parsed for these parameters.  This
provides a way for the user to change these parameters and default
values, if necessary.  See the file ".navion" in the navion home
directory for an example format; or just run the simulation and exit;
a sample format will be generated for you as ".simname", which can
then be edited.

General parsing rules:

  - blank lines and lines whose first non-blank character is '#' are
considered comments.

  - Indentation and most whitespace is ignored; the
simulation-generated file does some simple use of tabs and spaces to
make the output file more readable. Ends of line, however, are
important to the parser, so lines cannot (at present) be continued.

  - Indirection is allowed! A "dot" file may contain a line (outside
of a "facility/end" line pair) beginning with '@'. This is taken to be
a reference to another settings file that is to be opened and parsed.
This isn't too useful at present, but is there to be exploited. A
simulation generated "dot" file will not contain these, but their
effects on default settings will be recorded in the output settings
file.

  - Pathname is supported: if LARCSIMPATH is defined, it is expected
to be a colon-separated list of directories to be examined for the
"dot" file (and any initial conditions files given by the 'i' switch).

To protect a particular "dot" file from being overwritten at the end
of the simulation session, simply make it read-only ("chmod 444
.navion"); this will prevent it from being overwritten at the end of a
simulations session (and prevent a changed initial condition from
being recorded).


  == NEW PASSED PARAMETERS TO MODEL ROUTINES ==

As mentioned above, the higher-level model routines (aero(),
engine(), inertias(), gear(), and subsystems() routines) are now
called with two additional parameters: dt and and initialize flag. The
dt parameter, expected to be of type SCALAR, is the current loop's
time step size (it may vary from call to call); the initialize
parameter, of type int, indicates an initialization is called for if
non-zero.  In response to this flag being non-zero, the user-provided
routines should override any filters (set outputs to inputs) and take
other appropriate behavior for initialize, reset, or trim requests.
See the trim description above for an example.  This value of dt
should be used to drive other dynamic elements, such as hydraulic
actuators and control system filters.


*** CHANGE LOG ***

Changes since version v13:

ls_ACES.h: 	Swapped sense of landing gear switch.

ls_cockpit.h:	Swapped sense of landing gear switch; added
		throttle_pct field

ls_constants.h:	Added definition of PATHNAME & NIL_POINTER; added
		metric to english units conversion constants

ls_sim_control.h: Increased size of date & time fields to include
		terminating null; added paused flag; deleted
		tape_channels counter; added end_time, data_rate, and
		term_updated_hz flags.

ls_sym.h:	Added header; symbol_rec def'n; SYMBOL_NAME and
		SYMBOL_TYPE def'ns; and access routine prototypes and
		descriptions.

ls_tape.h:	Incorporated symbol_rec type in CHANNEL defn; made
		actual data vectors into pointers to vectors; length
		of data vectors is determined and memory allocated
		just prior to run to be more efficient and allow user
		to change buffer size.

LaRCsim.c:	Added terminating null to date_string & time_stamp;
		set userid field; moved setting of default options to
		separate function ls_setdefopts(); reworked logic on
		setting io_dt; added 'i' and 'o' switches; created
		separate ls_loop() function; added call to
		ls_get_settings() after setting default options and
		parsing command line options; added call to
		ls_put_settings(); modified loop execution logic to
		pass 0. value as dt when sim_control_.pause is
		non-zero; added mandatory parameter to -o flag; added
		'-b' and '-s' switches; made filenames following
		output writing flags '-r', '-t', '-x', '-a' mandatory.

ls_ACES.c:	Changed sense of landing gear switch.

ls_aux.c:	Fixed bug in calculation of beta_dot.

ls_ifgl.c: 	Moved 'paused' variable to sim_control_ common block;
		reworked pause logic so HUD indicates paused condition
		more accurately; changed VSI & lat/long readouts to
		use correct simulation generic variables V_down,
		D_cg_north_rwy, etc.; changed throttle readout from
		Throttle[3] to new global variable Throttle_pct; added
		call to ls_save_current_as_ic() if trim is successful;
		removed calls to sleep() for GLmouse mode (since sim
		now starts in paused state).  The sky will now darken
		(in RGB mode) as altitude increases in a non-linear
		fashion, to simulate orbital flight.

ls_ifsun.c:	Added header, swapped to use throttle[3]; changed
		sense of throttle keys a & s, set sim_type to
		terminal; added trim 't' command; renamed module name
		to "ls_ifterm.c"

ls_init.c:	Major changes: added ls_init_get_set() and put_set()
		routines, added ls_init_init() routine.

ls_model.c:	Inrorporated parameters in subroutine calls to pass dt
		and initialize flags.

ls_record.c:	Modified to use new symbol_rec structure in Tape
		channels; added ls_record_get_set() and put_set()
		routines; making use of ls_get_sym_val() routine;
		changed Tape allocation procedure to delay allocation
		of data vectors until first pass; put protection to
		avoid allocating more channels than allowed.

ls_step.c:	Added local variable local_gnd_veast to determine if
		eastward velocity due to earth's rotation is needed at
		initialization; added initialization of Alpha_dot and
		Beta_dot to zero on first pass.

ls_sym.c:	Added routines ls_print_findsym_error(),
		ls_get_sym_val() and ls_put_sym_val() routines.

ls_writeasc1.c:	Modified to use new Tape Channel structure.

ls_writeav.c:	Modified to use new Tape Channel structure.

ls_writemat.c:	Modified to use new Tape Channel structure.

ls_writetab.c:	Modified to use new Tape Channel structure.



Added new files:
  ls_matrix.h
  ls_matrix.c
  ls_settings.c
  ls_trim.c
  ls_ifterm.c (renamed from ls_ifsun.c)

Deleted files:
  ls_eom.h (no longer needed - use ls_types.h, ls_constants.h, and
		ls_generic.h as needed instead) 
  ls_ifsun.c (renamed to ls_ifterm.c)
