Surface Plotter - Syntax Reference


The syntax of functions in Surface Plotter is very much like the syntax of C language. For example: sin(x)/x
You should have no problems in learning how to define functions in Surface Plotter if you are familiar with programming language, such as C/C++, Pascal, Basic, Java, etc.
A function definition is made up of operators and operands, no matter how complex it is.

Operands

Operands are divided into two main categories: numerical operands and boolean operands.
Boolean operands are the result of applying relational operator to two numerical operands. (i.e: 2 < 3 results true, which is boolean type).
Numerical operands are constants, variables, and result of internal function calls.

Here are the details of numerical operands:

Constants

Surface Plotter defines two constants:

  e             natural number                    value = 2.7182818..
  pi            area of circle with radius 1      value = 3.14159265..
  

Variables

Valid variables are x and y.

References

References are user defined variables. They are used to break long functions into short pieces. Surface Plotter evaluates the values of these references and then treats them as a variable. See Using references to break long functions for detail.

Internal Functions

  abs(x)        returns the absolute value of x
  acos(x)       returns the arc cosine of x
  acosh(x)      returns the inverse hyperbolic cosine of x
  asin(x)       returns the arc sine of x
  asinh(x)      returns the inverse hyperbolic sine of x
  atan(x)       returns the arc tangent of x
  atanh(x)      returns the inverse hyperbolic tangent of x     
  ceil(x)       rounds x up to the nearest integer
  cos(x)        returns the cosine of x
  cosh(x)       returns the hyperbolic cosine of x
  exp(x)        returns the exponential of x 
  floor(x)      rounds x down to the nearest integer
  frac(x)       returns the fraction part of x
  int(x)        returns the integer part of x
  ln(x)         returns the natural logarithm of x
  log(x)        returns the base-10 logarithm of x
  round(x)      rounds x to the nearest integer 
  sign(x)       returns -1 if x < 0, 1 if x > 0, and 0 if x = 0
  sin(x)        returns the sine of x
  sinh(x)       returns the hyperbolic sine of x
  sqr(x)        returns x * x
  sqrt(x)       returns the square root of x
  tan(x)        returns the tangent of x
  tanh(x)       returns the hyperbolic tangent of x
  
  min(a,b)      returns the smaller value of a and b
  max(a,b)      returns the greater value of a and b
  atan2(a,b)    computes the phase theta by computing an arc tangent of b/a in
                the range -pi to pi
  mod(a,b)      returns the remainder of a divided by b as defined by IEEE 754 
  
Note:
  • All angles are measured in radian.
  • The parameter x,a,b may be replaced with any expression.
  • Surface Plotter's parser is case-sensitive. Use ONLY lower case characters.

Operators

Surface Plotter recognizes three kinds of operators: arithmetic operators,
relational operators, and boolean operators.
Relational operators and Boolean operators are used only in conjuction with "if" function.
Arithmetic operators are operators for manipulating numbers. They are the same with those BASIC programming language uses.
Here is the list of all valid arithmetic operators and their precedence.

Precedence of Operators

 
  ------------------------------------------------------------------------------
   Operator    Precedence      Operation         Category         Associativity
  ------------------------------------------------------------------------------
      +        First (high)    sign identity     unary            right to left
      -                        sign negation
  ------------------------------------------------------------------------------
      ^        Second          power             power            right to left
  ------------------------------------------------------------------------------
      *        Third           multiplication    multiplication   left to right
      /                        division                         
  ------------------------------------------------------------------------------
      +        Fourth          addition          addition         left to right
      -                        substraction
  ------------------------------------------------------------------------------        
  
Note: Expressions within parentheses are evaluated before being treated as a single operand.

Relational operators and Boolean operators

Since version 1.10, Surface Plotter's function parser recognizes relational operators and boolean operators.
Here is the list of valid relational operators and boolean operators:

  ------------------------------------------------------------------------------
   Operator    Operation                 Category         Operand Type(s)
  ------------------------------------------------------------------------------
      <        less than                 relational       numerical expression
      >        greater than              relational       numerical expression
      <=       less than or equal        relational       numerical expression
      >=       greater than or equal     relational       numerical expression
      =        equal                     relational       numerical expression
      <>       not equal                 relational       numerical expression
      &        logical and               boolean          boolean expression
      |        logical or                boolean          boolean expression
      !        logical inversion         boolean          boolean expression
  ------------------------------------------------------------------------------        
  
Note: All operators listed above produce boolean type result. The result can only be used as the conditional statement for "if" function.

The "if" function

The "if" function has the following syntax:

if(conditional statement, expression1, expression2)

Surface Plotter will evaluate expression1 if conditional statement is evaluated to true and expression2 otherwise.
For example, the result of the following statement

if(x < 0, -x, x)

is -x if x is less than zero and x otherwise (absolute of x)
The following expressions are also valid:

z = (fx,y) = sin(if(x < 0; 2*x, 3*x))
z = f(x,y) = if(x = 0,0,sin(x)/x) - 2

And for the last, you can nest "if" functions. For example, you can write sign(x) as:

z = f(x,y) = if(x <= 0, if(x = 0, 0, -1), 1)

Using references to break long functions

Suppose you want to define a function like this: z(x,y) = exp(1-cos(x)) / (y + exp(1-cos(x))

Soon you see that the function definition is long and inefficient. The exp(1-cos(x)) part appeared twice and it is more efficient to make a reference to exp(1-cos(x)), says a, and defines the overall function as: z(x,y) = a / (y + a).

Since version 1.30b1, Surface Plotter provides a way to do this. The syntax of references is:

reference name 1: definition 1; reference name 2 : defintion 2; ...

The reference name is theoritically can be any characters long, but it must not be the same with any of defined variables or constants (x, y, e, pi), function names (sin, cos, tan, ...), reserved words or operators (if, |, =, ...). In short, the reference must not make the original definition ambiguous. The reference name may not start with a number. (e.q: 1st, 2nd, ...) This restriction also apply in most (all ?) of computer language.

A function definition may contain many references, and a reference definition may contain other references, but it must not start with a reference. Surface Plotter evaluates references from back, so you must define a reference after you used it.

This makes circular references impossible.

Examples:

z(x,y) = a: sin(x); b: cos(y); a + b

  • Incorrect, must not start with a reference.

z(x,y) = a + b + c; a: cos(b); c: 2 * a

  • Incorrect (in c = 2 * a), must define a reference after used it.

z(x,y) = a / (1 + b + c); a: cos(b); b: 2 * x; c: x * cos(y)

  • Correct.

Send comments, suggestions, bug reports to Yanto Suryono