JGraph User Manual

(C) Thalion Graphic Solutions e.K 2001, all rights reserved

Contents

  1. Preface
  2. Introduction
  3. Invoking JGraph
    1. The Wrapper Script
    2. Files
  4. JGraph's User Interface
    1. Defining A Function
      1. The Definition Dialog
      2. Using MathC
    2. Plotting A Function
      1. The Plot Dialog
      2. Is it drawable?
      3. Visualization Options
    3. Printing
    4. Global Preferences
  5. The MathC function definition language

Invoking JGraph

The Wrapper Script

If you have successfully installed JGraph, a script called 'jgraph' has been created in <installdir>/bin. This script is referred to as 'wrapper script', because it wraps the actual startup of the JGraph software, providing all required environment settings like library paths and appropriate Java runtime flags.

From the user's point of view, the wrapper script lets JGraph appear like any application. Provided, the script is in your path, just type 'jgraph', to launch the software. You can also invoke the script passing additional arguments, where each argument must then name a file containing MathC function definitions.

Example: assumed, fdefs1.mc and fdefs2.mc were files located in the working directory, containing function definitions you wrote:

     // File fdefs1.mc
     foo(x:int,y:int) :int := x + y
     bar(x,y) := foo(x,y)
    

     // File fdefs2.mc
     fib(n:int) :int :=
        if n < 2 then 1 else fib(n-1) + fib(n-2)
    

You could then run jgraph issuing the command line: jgraph fdefs1.mc fdefs2.mc
This would launch the JGraph software and define foo, bar and fib, if the definitions were correct (else some error messages would be printed).

Files

During startup, jgraph tries to evaluate several files, if they exist, to determine site- and user-specific settings.

JGraph's User Interface

The Application Menu and Toolbar

JGraph's main window allows to start actions via it's menu bar or the toolbar shortcut icons.

New Definition(s) Icon Same as New ... menu item in file menu: open the function definition dialog - this allows to input user defined functions
Open File Icon Same as Open ... menu item in file menu: open a file selection box which allows to choose files to read function definitions from
Plot Function Icon Same as Plot ... menu item in file menu: brings up the plot dialog, allowing the user to select functions to visualize
Reset Icon Same as Reset menu item in file menu: clears the function repository, and closes all visualization windows in the same turn
Preferences Icon Same as Preferences ... menu item in Edit menu: opens the preferences dialog, which allows to customize global JGraph settings

Defining A Function

Except the specification of function definitions by passing MathC files, JGraph allows the input of user defined functions during runtime.

The Definition Dialog

The Function Definition Dialog
Fig.1: screenshot of the definition dialog

This dialog provides simple editing capabilities. You can type code inside the text area, and define either a previously marked and hilighted selection of this code, or everything contained by the text area. Use the button to define selections, and the button to define everything. If the MathC compiler detects any errors, JGraph will show a message box containing the error description.

Plotting A Function

The Plot Dialog

The Plot Dialog
Fig.1: screenshot of the plot dialog

The dialog's list box displays all currently defined functions. A function is shown whith it's name and it's type code (see next section for explanations). Select the function you wish to plot, by clicking into the list box and hilighting the corresponding item. If the function is plottable, a document window containing the visualization will appear, plus a set of controls allowing to customize the graph. If it can't be displayed, JGraph will inform you by popping up a message box containing the reason (usually, plotting fails because the function is not of one of the valid types, but there may also be runtime errors like infinite recursion, which caused a stack overflow in the internal interpreter system etc.).

Is It Drawable?

JGraph can only visualize a limited number of function types. Currently, it is, funny enough, not able to plot definitions using only one argument - only surface plots are possible.

So, all f(x,y)-stylish functions are valid, and you can also display f(x,y,z)-type definitions, where the third parameter may optionally be used to create '4D'-plots, whith 3rd space coordinate representing the f(x,y,z)-value and z itself proceeding over the time axis.

JGraph's built-in interpreter uses function prototype codes to identify legal plottable types. The interpreter can deal with a lot more prototypes, than the graphing system can display. A function prototype consists of a list of argument types, enclosed by parentheses, and a return type specification. Type codes are b for boolean values, i for integer numbers and f for floating point values. A sample prototype identifier would be (i)i, designating a function taking integer and returning integer types. (f)f would match all functions taking float and returning float, like the trigonometric functions sin, cos and tan. All available types may be used to form complex function definitions (see the MathC manual to read about how to do this), but only the ones accepting and returning float types are plottable.

Summary:

Visualization Options

JGraph provides a set of options to customize the appearance of function surface plots.

Print Icon Invoke the print dialog - this option allows to output the currently visible frame onto a printing device or into a (PostScript) file
Axes Option Icon Toggle the display of coordinate system axes in the scene
Contours Option Icon Toggle the usage of contour shades - if switched on, the plot will be shaded in different colors and intensities for different z-coordinate (f) values
Lighting Option Icon Toggle lighting - if active, the plot will be displayed in shades like it was lit by two independent light sources
Edit Light Source #0 Icon Edit Light Source #1 Icon Edit light source colors - these icons bring up a color chooser dialog allowing to modify the colors of both available sources
Select Points Mode Icon Select Wireframe Mode Icon Select Smooth-shaded Mode Icon Select shade mode - you can choose amongst drawing the function as a set of points, a wireframe model or a solid, smooth shaded body

Specifying Plot Ranges

Custom ranges can be specified by entering values into the set of text input fields provided by the document toolbar.

An Overview Of MathC

What Is It?

MathC is a small functional language, designed to support the explicit definition of numerically evaluable functions. It provides the base set of arithmetic operators on integer and float types, and boolean operations. You can define and call functions, and pass and return function references to and from other functions. Conditional evaluation and recursion are available as well, to allow you writing more complex definitions.

Expression Syntax

Operators

MathC supports 'common' infix notation of expressions, like

     a + ( b / c ) * d 
    
Predefined infix binary operators (operators, which are applicable to two operands enclosing them, like the add operator +) are:
+addnum + num
-subtractnum - num
*multiplynum * num
/dividenum / num
%modulonum % num
**powernum ** num
=equalsany = any
<less thannum < num
>greater thannum &lgt; num
<=less or equalnum <= num
>=greater or equalnum >= num
<>equals notany <> any
andlogical andbool and bool
orlogical orbool or bool
xorlogical exclusive orbool xor bool
Prefix unary operators (operators, which precede their operands, and are applicable to exactly one operand) are:
++ num
-negate- num
notlogical negatenot bool
_sinsine_sin float
_coscosine_cos float
_tantangens_tan float
_asinarcsine_asin float
_acosarccosine_acos float
_atanarctangens_atan float
Complex subexpressions may be formed by using enclosing parentheses ().

Coditional Expressions

MathC provides two syntactical structures for use in conditionals:

Values: Constants And Variables

So far, you know how to apply operations to values. But what exactly are values in MathC?

Quite easy: much the same as they would be in a numeric calculator: numeric constants like 0,1,4711 or 3.14159.

But MathC can do more. As a bit more advanced calculator offers a memory/recall facility, MathC can store and recall values in memory. To access such a value, you must use it's name, also known as identifier, which just consists of a sequence (one or more) of characters, usually forming a word of more or less meaning in a natural language's context. Such a name has to be determined at some place, of course. This is done by declaring it: either as a global constant, or as a function argument. Before you can use the identifier in expressions, MathC must have been informed about it by one of these two ways - explanations about how to do this follow.

Valid identifiers for MathC variables are for example:
f,g,f1,foo,a_variable,N,numberOne,n0,_n0

Global constants may be defined by using the const keyword. A definition looks like follows:
const var := const-value

For example, you may define the all-used constant PI via
const PI := 3.14159
After issuing this line of code, you can use the constant PI in any expression the same way as you would otherwise have used the number 3.14159. This means, you could legally write
_sin PI in an expression, getting the same result as if you wrote _sin 3.14159. If PI would not have been defined as described above either, MathC would confront you with some grumbling and ranting, and deny the evaluation of this operation.

The following section explains how to use function arguments.

Defining A Function

You have learned now, how to write expressions in MathC. But, of course, you also want to use them for some computations. MathC does not immediately evaluate expressions, but recalls them, in conjunction with information about how to parametrize them - a so called function.

So far you can compose 'static' expressions - they consist of constant values, either literal numbers or identifiers of constants, connected by operators. The second type of identifiers in MathC stands for objects, whose value may change, so called variables. They can be used the same way as constant identifiers, but are declared different: in the formal argument list of a function. Functions are the central part in MathC - in fact, the only way to actually compute something is to define a function and 'call' it using the required arguments.