Defining a Calculator

Orchestra calculators are defined in their own input file in terms of "native" keywords/objects (variables, expressions, unknown-equations) and user defined objects. The native objects are implemented in Java source code and cannot be changed by users. ORCHESTRA includes a set of standard chemical model objects that can be used by including this objects file in the calculator input file.

• Native Objects and keywords

  The native objects that can be used to define Calculators are: Variables, Mathematical Expresssions and Unknown-Equation pairs.

• Variables

  Any variable that is used in the calculations has to be defined first. This definition gives the variable a name and an initial or default value.

  A variable pH with an initial value of 7 is defined is as follows:

  @Var: pH 7

• Mathematical expressions

  Mathematical expressions are used to define all calculations that need to be carried out by the Calculator. These expressions have the following format:

  @calc:(<stage>, "<variable> = <expression>") 

  The stage indicates during which calculation stage the expression is calculated

  • stage 1 top down (calculation of activities,
  • stage 2 top down (calculation of concentrations),
  • stage 3 bottom up (calculation of cummulative mass balances per phase),
  • stage 4 bottom up(summation of mass balances over hierarchical phases).
  • stage 5 bottom up(calculations that have to be carried out after the previous stages).
  @calc:(1, " H+.act = 10^-pH ")

  List of ORCHESTRA mathematical functions;

  • sqrt(<expression>)
  • abs(<expression>)
  • log(<expression>)
  • log10(<expression>)
  • exp(<expression>)
  • sin(<expression>)
  • cos(<expression>)
  • tan(<expression>)
  • sinh(<expression>)
  • cosh(<expression>)
  • tanh(<expression>)
  • atan(<expression>)
  • max(<expression>,<expression>)
  • min(<expression>,<expression>)
  • if(<condition>,<expression>,<expression>)

  In earlier ORCHESTRA versions, calculations had to be defined in terms of relations. This is still possible, and to allow for gradual updating of your input files, old relations can be mixed with the new expressions. The complete set of old relations is shown here.

• Unknown-Equations

  An unknown equation pair is defined as follows:

  @uneq: <unknown> <start estimation> <equation> <given value> <relative error> <absolute error>

  @uneq: pH            7            H+.tot.sum        1e-4          1e-6          1e-12 

  From version 10/10/2003 it is possible to use a new type of Uneq:

  @uneq2: unknown:(name:, pH, type:, lin, delta:, 1e-5, step:, 1, min:, 0, max:, 14)   equation:(name:,  H+.tot.sum, type:, lin, tol:, 1e-8) 

  Parameters for the unknown variable definition

  • name: name of the unknown variable
  • type: lin/log indicates if log transformation of unknown is used during iteration
  • min: minimum value of unknown
  • max: maximum value of unknown
  • delta: delta unknown used in numerical determination of partial derivatives
  • step: maximum change of unknown value per iteration step

  Parameters for the equation variable definition

  • name: name of the equation variable
  • type: lin/log indicates if log transformation of equation is used during iteration
  • tol: tolerated absolute difference between given and calculated value of equation variable

These "native" objects are generic and allow the definition of arbitrary calculations. However, it would not be convenient to set up complete chemical equilibrium calculations directly in terms of native objects. The possibility to define user objects makes this much easier.

 

• User-Defined Keywords or Objects

  User defined objects are defined using the @class: keyword. Objects can be defined in terms of native keywords / objects and in terms of other objects. Have a look at the set of standard ORCHESTRA object definitions here:

  objectfile

Defining an Object class

@Class: name (parameter1, parameter2, ... )
Between the list of parameters and the bodytext you can put documentation text.
{
   bodytext <parameter1> 
}




Using an Object class

@name (parameter1, parameter2, ... )

 

• Other Keywords

  • @include: filename                  // includes filename in current file.

  • @max_iter: 100                      // sets maximum number of iterations.