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 --> SAVE --> SYSTEM ----- 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 Examples: DELETE pi DELETE a An opening parenthesis must follow function names. To delete a function type DELETE 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 Simply declares a new fundamental dimension. DIMENSION 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 is the conversion factor to the standard unit for the specified dimensions. 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 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 Save any dimensions, units, variables, or functions defined since startup. Data is written to file 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 Like SAVE, but saves all dimensions, units, variables, and functions, including those initialy loaded in from PHYSCALC.DAT. --> SYSTEM 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 ->