.TH clim "" "" "X Application"
.PC "Model planetary climate"
\fBclim \fImapfile\fB [\fIparameters\^\fB]\fR
.PP
The program
.B clim
computes the climate for an imaginary planet:
temperature, pressure zones, wind patterns, rain patterns,
and finally climate based on temperature and rain.
.PP
.I mapfile
gives the topography of the planet whose climate you are modelling.
You must use a map file; the argument `-' indicates the standard input.
.PP
.I parameters
names an optional file that sets parameters for
.BR clim ;
these parameters affect your planet's climate.
These are described in detail below.
.SH "What Does clim Do?"
Given a topographical map \(em for example, one produced by \fBtec\fR \(em
.B clim
computes temperature, pressure, wind, rain and climate.
The data used in these computations come from any college-level
meterology text.
Output is produced as an animation on the graphics screen, or in text
files including PostScript output.
.PP
File
.B /usr/X11/lib/planetge/clim.in
gives an example of
.B tec
output that can be passed to
.BR clim .
To run it, type:
.DM
	clim /usr/X11/lib/planetge/clim.in
.DE
.SH "How Do I Run It?"
To run
.BR clim ,
type its name followed by the name of the data file that maps the planet
whose climate you want it to model.
.PP
.B clim
opens a graphics screen.
It prints about 40 lines of status information to the standard-error
device, then begins to animate the results.
.PP
.B clim
recognizes the following commands from the keyboard:
.IP \fBC\fR 0.3i
Display climate.
The following colors are used:
.DS
      dark blue: Ocean
      orange: Savannah
      light grey: Icebergs
      dark green: Decidous forest 
      dark grey: Tundra
      bright green: Jungle
      brown: Steppe
      bright blue: Swamp
      yellow: Desert
.DE
.IP \fBH\fR
Display temperatures.
This is the default.
The full spectrum is used to display the temperature,
with the blue end of the spectrum indicating lower temperatures, and
the red end indicating higher.
There are about 30 visibly different shades.
Black lines indicate coastline; white lines surround mountains.
.IP \fBP\fR
Display atmospheric pressure.
Zones of low pressure are surrounded by white
lines; zones of high pressure are surrounded by black lines.
Ocean is blue, land is red, and mountains are gray.
.IP \fBQ\fR
Quit
.B clim
and close its window.
.IP \fBR\fR
Display mean annual rainfall.
Amount of rainfall is displayed using the full spectrum:
purple is driest, red the wettest.
Black lines indicate coastline; white lines surround mountains.
.IP \fBW\fR
Display wind patterns.
Winds run in circles, especially over the ocean.
Black horizontal lines are westbound; white horizontals are
eastbound.
Black vertical lines are southbound; white verticals are
northbound.
Ocean is blue, land is red, mountains are gray.
.PP
Please note that because
.B clim
is so CPU-intensive, it may not immediately detect a keystroke.
Please be patient.
.PP
You can use the command
.B tec
to produce maps to use as input for
.BR clim .
For details, see the manual page for
.BR tec .
.SH "clim Parameters"
As noted above, you can pass
.B clim
a file of parameters.
Some parameters affect the climate that
.B clim
models for your imaginary planet; others control how
.B clim
prints a climatery map.
Every parameter has a default;
thus, the parameter file need contain only the parameters
you want to change.
.PP
A parameter looks like LISP; for example, to change the parameter
.BR XSIZE ,
include the instruction
.DM
	(XSIZE 40)
.DE
.PP
in your parameter file.
.PP
Parameters can also be vectors; for example:
.DM
	(RAINCUT (40 60 110 160 180))
.DE
.PP
The following parameters affect printing and sizing:
.IP \fBXSIZE\fR
The horizontal size of arrays.
The default is 60.
.IP \fBYSIZE\fR
The vertical size of arrays.
The default is 30.
.IP \fBBSIZE\fR
Number of seasons in animation and computation.
The default is four.
Note that the storage arrays are statically sized with the constant
.B MAXB
(in
.BR const.h );
to increase
.BR BSIZE ,
you must increase
.B MAXB
and recompile.
.IP \fBPRINTMODE\fR
Value `4' produces PostScript output.
Any other value produces a short summary output.
The default is zero \(em that is, do not print any output.
\fBPRINTEMP\fR
Any nonzero value produces a text map for each season,
in which the entries use a single hexadecimal digit to
represent scaled temperature.
.B clim
also prints a key that contains the Farenheit
temperature equivalents for each digit.
Default is zero \(em that is, do not print a key.
.IP \fBPRINTPR\fR
Any nonzero value produces a text map for each season.
In this map, a `1' indicates a region of low pressure,
`2' a region of high pressure, and `3' the heat equator
(a zone of low pressure).
The default is zero \(em that is, do not print a map.
.IP \fBPRINTWIND\fR
Any nonzero value produces a text map for each season
in which the entries use one hexadecimal digit interpreted as
a bitmap.
Northbound winds are indicated by bit 0,
southbound by bit 1,
eastbound by bit 2, and westbound by bit 3.
For example, `5' indicates northeast winds.
The default is zero \(em that is, do not print a map.
.IP \fBPRINTRAIN\fR
Any nonzero value produces a text map for each season.
Entries are a single hexadecimal digit, with `0' indicating no rainfall
and `F' indicating maximum possible rainfall.
The default is zero \(em that is, do not print a map.
.IP \fBPRINTCLIM\fR
Any nonzero value produces one text map for each season.
Each entry is a digit, from zero to A.
The key is as follows:
.DS
.ta 0.5i 3.0i
	0  Ocean	7  Savannah
	3  Icebergs	8  Deciduous forest
	4  Tundra	9  Jungle
	5  Steppe	A  Swamp
	6  Desert
.DE
.IP
The default is zero \(em that is, do not print a map.
.PP
To produce a text file that show the climate and rainfall,
include the following instructions in your parameters file:
.DM
	(PRINTCLIM 1) (PRINTRAIN 1)
.DE
.PP
The rest of the parameters deal with the computational models.
.PP
The following parameters affect temperature:
.IP \fBTILT\fR
This is the tilt of the planet with respect to its plane of orbit,
in degrees.
The smaller this number, the less seasonality your planet has.
Numbers above 45\(de violate some of the assumptions of the models that
.B clim
uses.
The default is 23.0\(de.
.IP \fBECCENT\fR
The eccentricity of the planet's orbit, that is, how elliptic its orbit is.
This parameter affects seasonality as well.
Numbers above 0.5 are probably unrealistic.
The default is 0.0.
.IP \fBECCPHASE\fR
This parameter describes the phase offset of the
eccentricity with respect to the tilt, in radians.
You can produce climates with complicated seasonality by varying this.
The default is 0.0.
.IP \fBLCONST\fR
The basic temperature for land squares, assuming
no tilt, eccentricity, or nearby ocean.
The default is 275.0.
.IP \fBLCOS\fR
The amount by which land temperatures should vary
from north pole to equator.
Land temperature, ignoring ocean effects, varies from
.DM
	LCONST - LCOS/2
.DE
.IP
at the poles to
.DM
	LCONST + LCOS/2
.DE
.IP
at the equator.
The default is 45.0.
.IP \fBLTILT\fR
The fraction of the tilt parameter that should be
applied to temperature adjustment for land.
Typically, land temperatures vary more from season to season than the ocean
temperatures do, so
.B LTILT
should be higher than
.BR OTILT .
The default is 1.0.
.IP \fBLSMOOTH\fR
One equation governs the effect of land temperatures and ocean
temperatures on each other.
The equation involves the parameters
.BR LSMOOTH ,
.BR LDIV ,
.BR OSMOOTH ,
and
.BR ODIV .
Given the land and sea temperatures and
the number of land squares in a 11\(mu5
box around the square,
the final temperature is a weighted sum of the two temperatures.
The weights are related to parameters
.B LSMOOTH
and
.BR OSMOOTH .
The importance of nearby land is diminished by increasing
.B LDIV
or
.BR ODIV .
The default is 0.6.
.IP \fBLDIV\fR
The is described above.
Its default is 180.0.
.IP \fBOCONST\fR
This is the same as parameter
.BR LCONST ,
except that it is for the ocean.
Its default is 275.0.
.IP \fBOCOS\fR
This is the same as
.BR LCOS ,
except that it is for the ocean.
Its default is 30.0.
.IP \fBOTILT\fR
This is the same as parameter,
.BR LTILT ,
except that it is for the ocean.
Its default is 0.2.
.IP \fBOSMOOTH\fR
This is the same as parameter
.BR LSMOOTH ,
except that it is for the ocean.
Its default is 0.2.
.IP \fBODIV\fR
This is the same as parameter
.BR LSMOOTH ,
except that it is for the ocean.
Its default is 250.0.
.PP
The following parameters affect atmospheric pressure:
.IP \fBOLTHRESH\fR
Ocean pressure zones essentially ignore land masses, like islands,
whose radius is equal to or less than this number.
The default is one.
.IP \fBOOTHRESH\fR
Ocean pressure zones must be at least this many 
squares away from the nearest non-ignored land mass.
The default is five.
.IP \fBOLMIN\fR
If the unscaled temperature of an ocean square is
greater than
.B OLMIN
and less than
.BR OLMAX ,
then that square is a low pressure zone.
The default is 40.
.IP \fBOLMAX\fR
See above.
The default is 65.
.IP \fBOHMIN\fR
If the unscaled temperature of an ocean square is greater than
.B OHMIN
and less than
.BR OHMAX ,
that square is a high-pressure zone.
The default is 130.
.IP \fBOHMAX\fR
See above.
The default is 180.
.IP \fBLOTHRESH\fR
Land pressure zones essentially ignore bodies of water, like lakes,
whose radius is less than or equal to this number.
The default is three.
.IP \fBLLTHRESH\fR
Land pressure zones must be at least this many
squares away from the nearest non-ignored mass of water.
The default is seven.
.IP \fBLLMIN\fR
If the unscaled temperature of a land square is
greater than
.B LLMIN
and less than
.BR LLMAX ,
then that square is a low-pressure zone.
The default is 220.
.IP \fBLLMAX\fR
See above.
Default 255.
.IP \fBLHMIN\fR
If the unscaled temperature of a land square is greater than
.B LHMIN
and less than
.BR LHMAX ,
then that square is a high-pressure zone.
The default is zero.
.IP \fBLHMAX\fR
See above.
The default is 20.
.PP
The following parameter affects the winds:
.IP \fBBARSEP\fR
Winds are determined from pressure.
.B clim
builds a smooth pressure map, ranging from zero through 255,
by interpolating between highs and lows.
Wind lines are contour lines on this map.
This parameter indicates the pressure difference between lines on the map.
The default is 16.
.PP
The following parameters affect rainfall:
.IP \fBMAXFETCH\fR
The term
.I fetch
describes how many squares a given wind line travels over water.
A high fetch indicates a moist wind.
This number is the maximum depth for the tree-walking
algorithm that finds fetch;
the effect of wind in one square can travel no more than this number
of squares before stopping.
The default is five.
.IP \fBRAINCONST\fR
This is the base amount of rainfall in each square.
The default is 32.
.IP \fBLANDEL\fR
This is the amount by which rainfall increases
in every land or mountain square; that is, rainfall goes down.
The default is \-10.
.IP \fBMOUNTDEL\fR
For each unit of fetch that is stopped by a mountain,
rainfall in the mountain square increases by this amount.
The default is 32.
.IP \fBFETCHDEL\fR
The amount of rainfall in a square increases by
this number for each unit of fetch in the square.
The default is four.
.IP \fBHEQDEL\fR
The amount of rainfall in a square increases by
this amount if the square is on the heat equator.
The default is 32.
.IP \fBNRHEQDEL\fR
The amount of rainfall in a square increases by
this amount if the square is next to a square on the heat equator.
The default is 24.
.IP \fBFLANKDEL\fR
The amount of rainfall in a square increases by
this amount if the square is on the ``flank'' of a circular wind pattern.
This happens when the wind blows south.
The default is \-24.
.IP \fBNRFDEL\fR
The amount of rainfall in a square increases by
this amount for each adjacent square that is on a ``flank.''
The default is \-3.
.PP
Finally, the following parameters affect climate determination:
.IP \fBICEBERGK\fR
If an ocean square is below this temperature
(measured in degrees Kelvin) all year round,
then the ocean square is filled with icebergs.
The default is 263\(deK.
.IP \fBTEMPCUT\fR
The climate array is 4\(mu5.
The first index is based on average annual temperature.
The temperature is relative, based on the range of zero through 255;
this vector determines the cutoff points.
For example, with the default vector, a scaled temperature of 20\(de
falls into the first ``bin'' and 121\(de into the fourth.
Default is the vector (0 40 90 120).
.IP \fBRAINCUT\fR
The second index of the climate array
is based on average annual rainfall, scaled into
the range of zero through 255.
This vector determines the cutoff points.
For example, rainfall of 35 falls into the first ``bin.''
Default is the vector (40 60 110 160 180).
.IP \fBMTDELTA\fR
This is the amount, in degrees Farenheit, by which
temperature in the mountains decreases before the climate lookup is performed.
Default 20\(deF.
.SH "See Also"
.B
globe,
tec,
X applications
.R
.SH Notes
You must invoke
.B clim
with a data file.
If you do not, it perishes none too gracefully.
.PP
Copyright \(co 1991 by David Allen (allen@viewlogic.com).
You may distribute this freely as long
as you leave the author's name and copyright notice intact.
The author invites your comments.
Please send e-mail to the above address, or send surface mail to
David Allen, 10 O'Moore Ave., Maynard, MA 01754.
