
   Documentation for
PhysCalc by Marty White


Table of Contents
-----------------

    There are no page numbers.  These lines are exact copies of the title for
each section, so to quickly find a section, search for the same line.

----- License & Disclaimer
----- Introduction
----- Notation
----- What are dimensioned (or dimensional) numbers?
----- Expressions
----- Fractions
----- Dimensions
----- Operators and Functions
----- PhysCalc commands:
--> ?
--> QUIT
--> INFO
--> LET
--> DEFINE
--> LIST
--> DELETE
--> FACTOR
--> TRACE
--> FRACTION
--> BASE
--> DIMENSION
--> UNIT
--> LOAD <filename>
--> SAVE <filename>
--> SYSTEM <command>
----- Data files
----- Miscellaneous Details
----- WARNING
----- Command Line Arugments

-------------------------------------------------------------------------------


----- License & Disclaimer

PhysCalc
Copyright (C) 1990  Marty White

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Marty White
vulcan@lightlink.com    
http://www.lightlink.com/vulcan
390 West Candor Road
Candor, NY 13743


----- Introduction

    PhysCalc is a physics calculator.  It provides you with the power of a
programable scientific calculator and a universal unit converter all in one.

    The general operaton of PhysCalc is to enter commands or expressions at a
prompt and then PhysCalc does something.

    When you run PhysCalc, you are presented with an opening screen, the
contents of PHYSCALC.DAT are loaded in, and you are presented with a '>'
prompt.
    At the prompt you may enter a command or an expression to be immediately
evaluated.  Commands start with a keyword and take various parameters.
Expressions are evaluated using standard algabraic precedence, the user is
prompted for a unit to convert to when applicable, and the result displayed.


----- Notation

    PhysCalc completely ignores case, but in the documentation I have
capitalized many things to aid the reader.


----- What are dimensioned (or dimensional) numbers?

    A dimensioned or dimensional value is a number with a unit, such as 23
METERS or 12.3 LIGHTYEARS PER SECOND.  The units are considered an integral
part of the number.  PhysCalc consideres dimensional numbers, floating points,
integers, and fractions to each be distinct kinds of numbers:

        42 is an integer
        23.6 is a floating point number
        6.7 hours is also a dimensioned number
        5 days is a dimensioned number
            (and is automatically converted to 5.0 days)
        1\3 is a fraction (one third)

    The units available to PhysCalc are entirely up to you.  PhysCalc comes
with around 200 units, but you may change these or create your own.

    You may also use compound units such as METERS PER SECOND or NEWTON
METERS.  If PhysCalc knows what METERS and SECONDS are, it automatically knows
what METERS PER SECOND are.  "PER" is a unique keyword that you may use, and
it means to divide one unit by another.  All units may use metric prefixes
such as "KILO" and "MICRO", and the unit is scaled appropriately.  Units may
be abbreviated, but abbreviations are really treated as entirely distinct
units (the units that come with PhysCalc include some abbreviations such as M
for METER, S for SECOND, and N for NEWTON).  Scaling prefixes may also be
abreviated, with the unfortunate requirement that abbreviations be
unambigious, which rules out many of them (does MM mean MILLIMETER, MEGAMETER,
MICROMETER, or MYRIAMETER?).  Most units may be entered as singular or plural.
And lastly, all units may be raised to (non-zero) integral powers using the
exponent operator as in METER^3.  To properly specify a unit to a power, there
must be no spaces between the unit and the exponent operator (if there is, the
meaning changes).

    You may combine all of thse as much as you like:

  AMPERE MEGAMETERS^4 PER CENTIDOLLAR S^-2 PER DECAKELVIN MICROMILLIGRAMS

is a perfectly valid unit, equivalent to

  AMPERE DECAKELVIN NANOGRAMS MEGAM^4 SECONDS^2 PER CENTIDOLLARS

but don't ask me what it means!

Summary:
    - Units may be compound, including use of "PER".
    - Metric prefixes (and their unambigious abbreviations) may be used.
    - Abbreviations for units may be defined and used.
    - Units may be plural or singular.
    - Units may be raised to integral non-zero powers by using the '^'
        operator with no spaces in between.


----- Expressions

    An expression is a calculation to be done.  The simplest expression is
just a number:

        18 METERS

    or it can involve operations:

        4 METERS + 12 YARDS

    These may be simply entered at the prompt.  PhysCalc will evaluate the
expression and display the result, with one further feature: if the result is
a dimensioned number (like 8 meters), you will be prompted for the units to
convert the result to.  Internally, all computations are done with a "base"
set of units, normally metric, but you may want your answers in English units
or kilo- units or what not.
    When prompting you for a unit PhysCalc displays the dimensions the unit
must account for: distance, time, mass, and the like.  Example exchange:

    >55 miles per hour                           |  User enters expression.
      DISTANCE PER TIME  (VELOCITY)              |  Dimension is displayed.
    Convert to: km per hour                      |  User enters output unit.
    Answer: 88.5139 km per hour                  |  Answer is displayed.

    Here, the user entered a quantity in miles per hour and converted it to
killometers per hour.  The dimensions of miles per hour and kilometers per
hour were distance per time.  PhysCalc happened to know that this was
equivalent to velocity, and helpfully said so (vital when working with very
compound units).  If the user didn't know of any units for velocity, a
question mark could have been entered and a list something like this would
have been displayed:

      DISTANCE PER TIME  (VELOCITY)
    KNOT
    C
    Default unit is METER PER SECOND

    Here, PhysCalc has predefined units KNOT and C (speed of light), and
always generates a default compound unit from the internal base units.  If
your unit is strange enough (like SECONDS^2), there will be no predefined
units and you will have to enter a compound unit (like DAYS^2 or DAY HOURS).


----- Fractions

    This program also works with fractions.  Fractions may be entered using a
a backslash '\' to separate the whole number, numerator, and denominator. Some
sample expressions using fractions:

    1\2 + 0.0
    Result = 0.5
    1\1\2 + 0.0
    Result: 1.5
    1\2 + 1\3
    Result: 5\6


----- Dimensions

    Dimensions are very simliar to units.  All units are defined in terms of
dimensions, which to PhysCalc are just names.  The fundamental dimensions that
come with PhysCalc are DISTANCE, TIME, MASS, ANGLE, QUANTITY, and TEMPERATURE.
Dimension MONEY and its units are in the file MONEY.  A compound dimension may
be defined in terms of the base units just like a compound unit may be defined
in terms of other units.  Dimensions however cannot have scaling prefixes
(What does "MEGATIME" mean??).


----- Operators and Functions

    PhysCalc comes with built in operators and functions.  All operators and
functions do their best to work with dimensional numbers, but if you do
something impossible (like add meters to days or raise a dimensioned number to
a non-integral power), you will be warned and the result will have no
dimensions (and probably no meaning!).
    With the exception of trigonometry functions and the square root function,
built in functions do not accept dimensioned numbers.  The square root
function will work properly only with a few types of dimensions, such as
area. (Actually, area is the only dimension I know of which makes sense to
square root).
    If not specified by the user, trigonometry functions assume their
arguments are in unit RADIANS and that RADIANS is the base unit defined for
dimension ANGLE.  Inverse trig functions will always return a
unit of dimension ANGLE, which you will need to convert to RADIANS or DEGREES
(or your own angular unit).  If dimension ANGLE is not defined, the results
are unpredictable (Anotherwords, never delete dimension ANGLE, and don't
change the base from radians).


The following operators (in order of precedence) may be used:

    parenthesis             ( )
    negation,               - ~
        bitwise not
    exponentiation          ^
    factorial               !
    boolean not             not
    multiplication,         * / mod
        division, and
        modulo
    addition and            + -
        subtraction
    bitwise and             &
    bitwise or              |
    boolean and             and &&
    boolean or              or ||


Built in functions are as follows:

    exp(x)  - returns e to the x power
    ln(x)   - returns the logarithm of x, base e
    log(x)  - logarithm base 10
    sqrt(x) - square root
    fact(x) - factorial, x must be a small integer

    sin(x),
    cos(x),
    tan(x) - Trig functions. x is in radians, unless other angular units are
                specified (as in sin(90 degrees)).

    arcsin(x),
    arccos(x),
    arctan(x) - Arc-trig functions. These return dimensioned units, so you
                will be asked to specify an angular unit (degrees, radians).

    integrate(f,a,b[,p]) - definite integral of f on the interval from a to b.
                            The trapezoidal rule is used with p partitions.
                            If not given, the last number of partitions
                            specified is used. (Default p=20)


----- PhysCalc commands:

--> ?

    Querry about dimensions and units.  A plain question mark will dump a
list of all defined dimensions and units.  A question mark followed by a
dimension or unit (or compound dimension or unit) will display the same
information you'd get while doing a conversion of that unit - a list of
compatable dimensions and units.


--> QUIT

    Does just that, no questions asked.


--> INFO

    Displays some information about the program:
        - Version and compilation date & compiler.
        - Maximum space for fundamental dimensions.
        - Number of nodes currently allocated.


--> LET

    Assign a value to a variable name.  Variable names may be up to 18 letters
long.  For example:

    LET lightspeed = 3e8 meters per second
    LET a = sqrt(c^2 - b^2) + 7

    In the second example, the value (SQRT(C^2 - B^2)+7) would not be
evaluated until variable (a) was called for, at which time the values of (c)
and (b) would be looked up.  A variable can be used in place of any value.
You cannot, however, put unit names after a variable as in (N METERS PER
SECOND).  In such a case, simply use (N * 1 METERS PER SECOND).

    To force immediate evaluation when assigning a variable, use ':=' in place
of '=' as in:

    LET b := a+2

    Here, (a) will be evaluated right away, and (b)'s value will not change if
(a)'s does.  This saves time and memory (and possibly some aggravation).


--> DEFINE

    Define a function. Examples:

    DEFINE f(x) = 2 * x^2 - (1/3) * x + 3.5
    DEFINE square(number) number * number
    DEFINE funny_func(zip,zap,ping) = zip^3 / 12 megawatts * (zap + ping)
    DEFINE constant(c) = 42

    User-defined functions may be used just like built in functions.  Regular
variables may be referenced, but variables with the same names as dummy
paremters will not be accessible:

    LET X = 42
    LET Y = 3
    DEFINE F(X) = X^2 + Y
    F(2)
    Result: 7
    F(x)
    Result: 1767

    User functions may have multiple parameters and may be used with the
integrate function.


--> LIST

    Lists all variables and/or functions

        LIST        - lists variables and functions
        LIST VAR    - lists variables
        LIST FUNC   - lists functions


--> DELETE

    Deletes a variable or function. To delete a variable, type

        DELETE <variable name>

    Examples:

        DELETE pi
        DELETE a

    An opening parenthesis must follow function names.  To delete a function
type

        DELETE <function name><opening parenthesis>

    Examples:

        DELETE f(
        DELETE g()


--> FACTOR

    Lists all factors and the prime factorization of an integer value.

        FACTOR 1984 + 5

    would list all factors of 1989 and its prime factorization.


--> TRACE

    Turns tracing mode on or off: TRACE ON or TRACE OFF.
    In tracing mode, each step of a calculation is displayed on the screen so
you can see what it is doing.  It's not very readable, though.  Use CTRL-S or
CTRL-NUMLOCK to pause if the display scrolls by too fast.


--> FRACTION

    Sets fraction display mode.

    FRACTION IMPROPER   - displays fractions as numerator\denominator.
    FRACTION MIXED      - displays as integer\numerator\denominator.


--> BASE

    Set numeric base used for output, and default for input.  An equal sign is
optional.  You can set the base from 2 to 36.  The base itself is specified in
decimal.

    BASE 10     - set to base 10 (decimal, startup default)
    BASE = 16   - set to base 16 (hexadecimal)
    BASE 8      - set to base 8 (octal)

  A number is assumed to be in the default base, unless prefixed by a base
indicator: 0x, 0d, or 0b, for hex, decimal, and binary.

        0x10 + 0d10 + 0b10

    is the same as (16 + 10 + 2), which is 28 (base 10).


--> DIMENSION

    Defines a new dimension.

        DIMENSION <dimension name>

    Simply declares a new fundamental dimension.

        DIMENSION <dimension name> <dimensionality>

    Declares a compound dimension. An example:

    DIMENSION DISTANCE                   ;declare dimensions DISTANCE and TIME
    DIMENSION TIME
    DIMENSION VELOCITY DISTANCE PER TIME ;delcare compound dimension VELOCITY


--> UNIT

    Defines a new unit. Usage:

        UNIT <name> <factor> <dimension>

    <factor> is the conversion factor to the standard unit for the specified
dimensions.
    <dimension> can be a dimension description, as in the DIMENSION command,
or it can be a previously defined unit.  The first simple unit defined for a
fundamental dimension should be 1.0 (if you want valid calculations) and
becomes the base unit for that dimension.  Entering the name of a dimension
(as opposed to a unit) as the third parameter to UNIT is equivalent to
defining the unit in terms of the base unit(s) for that dimension.

Examples:

    UNIT METER 1.0 DISTANCE  ;METER will be the standard unit
    UNIT FOOT .3048 DISTANCE ;a foot is .3048 the size of the standard unit
    UNIT YARD 3 FOOT         ;a yard is 3 feet


--> LOAD <filename>

    Loads in a text file containing dimension, unit, function and variable
definitions.  Each line of the file is executed as if typed at PhysCalc's
regular prompt. A semicolon marks the begining of a comment, and the rest of
that line is ignored.
    Duplicate DIMENSION and UNIT definitions are ignored; duplicate variable
and function definitions replace previous ones (just like at the prompt).

Some sample data files are provided:
    PHYSCALC.DAT    Required at startup. Contains many default dimensions
                        and units.  You may edit this as you like.
    ASTRONOMY       Some astronomical units and constants.
    BYTE            Dimension INFORMATION, and associated units.  This one
                        is a bit of a kludge, since scaling prefixes have
                        different meanings (a kilobyte isn't 1000 bytes...)
    EXOTIC          Contains infrequently used units.
    MONEY           Contains the dimension MONEY and some units for U.S.
                        currency.
    PHYSICS         Contains functions and physical constants.


--> SAVE <filename>

    Save any dimensions, units, variables, or functions defined since startup.
Data is written to file <filename> as human-readable text (which may be
edited).  This will not re-save the contents of the PHYSCALC.DAT file, which
is loaded on startup, but only subsequent definitions.

SAVE ALL <filename>

    Like SAVE, but saves all dimensions, units, variables, and functions,
including those initialy loaded in from PHYSCALC.DAT.


--> SYSTEM <command>

    Attempts to execute the given shell command.

        SYSTEM DIR

    would do a directory on WinDOS systems.


----- Data files

    The file PHYSCALC.DAT must be in the default directory at run time.  It is
ASCII text and may be customized for your use.  It contains standard
dimension, unit, function, and variable definitions.

    If you wish to customize PhysCalc, just edit the PHYSCALC.DAT file to
include (or exclude) desired setup commands, units, dimensions, ect. Data
files can also be loaded or saved from within PhysCalc.

    PhysCalc stores its data in standard ASCII human-readable files as a
sequence of commands, as if entered into the program directly at the prompt.
Comments are preceded by a semicolon (;) and are ignored by PhysCalc.

    DIMENSION commands normaly come first, followed by UNIT commands and then
any others.  This ordering does not need to be kept, but Dimensions must be
defined before units of those dimensions, and Units must be defined before
using them.


----- Miscellaneous Details

    The abreviated version of a unit must be defined AFTER the un-abreviated
version.
    Re-defining a prefix for a given unit is valid:
        UNIT KILOBYTE 1024 BYTES

    All units can have the following prefixes:
        exa     e
        peta
        tera    t
        giga    g
        mega
        kilo    k
        hecto
        deca
        deci
        centi   c
        milli
        micro
        nano    n
        pico
        femto   f
        atto    a


    When PysCalc tries to identify a unit or dimension you have entered, it
uses this search algorithm:

        de-pluralize name
            compare with dimension names
            compare with unit names
                including any defined abbreviated unit names
            see if there's a scaling prefix (mega, kilo, ect.)
                if a prefix is found, remove it and start the search again.

    Plurals are automatically converted to singular using simple spelling
rules, with built in exceptions for "inches" and "calories":  Words ending in
"ies" are changed to end in "y".  If a word ends with a single "s", the "s" is
truncated.

    When entering dimensions with powers, the '^' must immediately follow the
unit. Use (meters^2), NOT (meters ^ 2) to indicate area.  This is so the
program can distinguish between things like 12 square meters and 12 meters to
the power of 2, which is 144 square meters, definitely not the same!  You can
always use parentheses to avoid ambiguity.

    All text files are currently tabulated using a tab size of 4 characters.
Tabulation does not affect the functioning of PhysCalc, only the readability
of text files.


----- WARNING

    There is currently a bug in PHYSCALC when working with large integers.
They are not always converted to real numbers when they should be. This
usually results in an unexpeccted zero or negative answer.  You can avoid this
by explicity using real numbers.


----- Command Line Arugments

    You can pass a physcalc command or expression on the command line and it
will then be executed and the program exited.  This can be used for quick and
easy computation straight from the command line.  Example:

        PHYSCALC 2.5 CUPS = FLUIDOUNCES

    Physcalc also accepts a "/Q" on the command line to suppress the normal
introductory text.  The text is automatically suppressed if an expression is
given.


----- Changes from version 2.3 to 2.4

    * Ported to Linux & Win32.
    * Fixed bug with certain plural units
    * Fixed bug with trig functions recognizing units of angle
    * Added overflow check to factorial operator
    * Renamed "DOS" command to "SYSTEM"
    * Added "BYE" as another alias for "EXIT"

EOF ->