A Brief Overview of In-Form

Summary

In-Form is a feature which enables users of PHOENICS greatly to extend its capabilities, without the introduction of new coding.

Users are enabled to express their requirements by way of formulae. These are read by the Input Module (Satellite), which transmits them to the Solver Module (EARTH); this then interprets them and performs the implied computations.

Unlike PLANT, its predecessor in functionality, In-Form does not require use of a re-compilable version of PHOENICS.

This document provides a brief overview of In-Form. The complete documentation can be found here.

Contents

1. Syntax
2. KEYWORD
3. VARIABLE
4. LOCATION
5. FORMULA
6. CONDITION
7. Examples
8. The In-Form Editor

Syntax

The syntax of In-Form is relatively simple. A typical In-Form command will have some if not all of these elements:

(KEYWORD of VARIABLE at LOCATION is FORMULA with CONDITION)

• KEYWORD defines what the In-Form command is setting.
• VARIABLE defines which SOLVEd or STOREd variable it is to apply to.
• LOCATION defines where
• FORMULA defines what
• CONDITION sets the conditions under which it will happen.

It should be noted that:

• The opening and closing brackets of the statement must always be present.
• The opening bracket must start in the first or second column.
• Lines must not extend beyond the 68th column; but a dollar sign, $, in or before the 68th column will be taken as an append-next-line instruction. Only one appended line is allowed.
• Characters may be upper- or lower-case without consequences.
• Blank spaces separate the items, several successive spaces having the same effect as one.

KEYWORD

The most commonly-used keywords include:

• PROPERTY - This keyword sets one of the physical properties. In this case, the VARIABLE keyword is the property to be set. It can be one of:

  RHO1 DRH1DP RHO2 DRH2DP ENUT ENUL PRNDTL PHINT TMP1 TMP2 EL1 EL2 CP1 CP2 DVO1DT DVO2DT CFIPS CMDOT CVM

  A full description of each of these is given here.

  The FORMULA keyword defines the value of the property.

  The LOCATION or CONDITION keywords can be used to limit the region of applicability of the FORMULA.

   

• STORED - This keyword is used for the creation of auxiliary variables which can have distinct values for each cell in the domain. A full description is given here.

  Such variables are of two main kinds, namely:

  • those which are used only for post-processing purposes, as when exact solutions are computed for comparison with the numerically-derived values or non-standard derived quantities are required; and
  • those which require to be updated continually during the computations because their values influence how the computation proceeds.

  The VARIABLE keyword is any name of the user's choice, up to 4 characters long. A list of names already used by PHOENICS, and which should therefore be avoided, is given here.

  The FORMULA keyword defines the value of the auxiliary variable.

  The LOCATION or CONDITION keywords can be used to limit the region of applicability of the FORMULA.

   

• INITIAL - This keyword sets the initial value of a STOREd or SOLVEd variable. A full description is given here.

  The VARIABLE keyword specifies which variable is to have its initial value set.

  The FORMULA keyword defines the initial value of the variable.

  The LOCATION or CONDITION keywords can be used to limit the region of applicability of the FORMULA.

   

• SOURCE - This keyword is used for introducing formulae defining the sources of mass, momentum, energy and other conserved properties. A full description is given here.

  The VARIABLE keyword specifies which variable is to receive the source.

  The FORMULA keyword defines the source.

  The LOCATION or CONDITION keywords can be used to limit the region of applicability of the FORMULA. The CONDITION keyword also affects the type of source.

   

There are other less-commonly used keywords, which are listed in the full In-Form documentation

VARIABLE

This keyword defines the variable the In-Form statement is to operate on. It can be any of the SOLVEd variables, or any of the auxiliary variables declared by STORE, or by the In-Form STORED command.

LOCATION

This keyword defines the location where the In-Form command will be applied. If it is absent, the command will apply to the whole domain.

LOCATION can be one of:

• The name of an OBJECT; or
• The name of a PATCH

More details are given here.

If different formulae are required at different locations, a separate In-Form statement will be needed for each location.

FORMULA

This is the formula, long or short, simple or complex, which describes what the In-Form is trying to implement. A full description is given here.

The formulae employed by In-Form, whether for setting properties, initial values, sources or anything else, are arrangements of operators, functions and operands which conform to rules which are similar to those of algebra and/or Fortran.

No significance attaches to whether upper- or lower-case characters are used.

Operators

The operators which may be used are:

• = + - * / ( ) , all of which have their usual significances; and
• ^, which represents exponentiation, thereby replacing the ** of Fortran;

Functions

The functions, listed in alphabetical order here, include:

• conventional mathematical functions:
  • ABS ACOS ASIN ATAN COS EXP MAX MIN SIN SQRT TAN, which have their Fortran significances, except that it should be noted that:
    • MAX and MIN operate on real values, thereby replacing the AMAX1 and AMIN1 of Fortran ;
  • LOGE which stands for the natural logarithm, with base e;
  • LOG10 which stands for the Napierian logarithm, with base 10.0 .

  formula-name functions:

  • POL2 POL3 POL4 POL5 POL6, which signify that a polynomial of the appropriate order is to be used:
  • PWL3, which signifies a piece-wise-linear function, with three parts;
  • SPL5, which signifies a cubic-interpolation spline function passing through five points; and
  • PWLF, which signifies a piece-wise linear function of which the defining points are specified in a file;
• neighbour-location functions:
  • EAST, WEST, NORTH, SOUTH, HIGH, LOW and OLD, which have meanings which are conventional in PHOENICS.

CONDITION

There are numerous post-formula options; but many of them apply only to particular keywords, as is shown here. If more than one 'with' condition is required, they must be separated by ! rather than 'with'.

There are two which apply to many keywords, these being:

• IMAT
• IF

Limitation to a particular material by use of 'with IMAT' etc

• It is possible to limit the action of a formula to those locations at which the material-property index, IMAT (alias PRPS), has a specific value.
• The complete set of 'with IMAT' conditions allowable in In-Form statements is:

  'with IMAT>value'

  means 'for PRPS greater than value'

  'with IMAT<value'

  means 'for PRPS less than value'

  'with IMAT>=value'

  means 'for PRPS greater than or equal to value'

  'with IMAT<=value'

  means 'for PRPS less than or equal to value'

  'with IMAT=value'

  means 'for PRPS equal to value'

  'with IMAT!=value'

  means 'for PRPS not equal to value'

Other variables than PRPS can be used in a similar way. Thus, it is possible to:

• define a new whole-field-stored "MARK" variable;
• use In-Form to ascribe values for it over the whole field;
• ascribe to density one value where (and when) the marker exceeds a prescribed value, and another when it falls below the prescribed value.

IF

Another generally-applicable post-formula option is the "IF( condition)" construct, wherein condition can be a Fortran-like expression, as exemplified in many library cases.

Note that blank spaces must not be used inside the IF() condition.

    'with IF(MARK.EQ.1)' is correct

    'with IF(MARK .EQ. 1)' will produce errors.

Examples

Here are some simple examples of using In-Form:

• Create a new 3D variable which contains the absolute pressure, P1+PRESS0, only in fluid cells (i.e. those with PRPS less than 100):

  Save7begin
(stored of PTOT is P1+PRESS0 with imat<100)
  Save7end 

• Make density a quadratic function of temperature (TEM1) everywhere:

  Save9begin
(property RHO1 is 1.0+0.1*TEM1+1.E-6*TEM1^2)
  Save9end 

• Make density a quadratic function of temperature (TEM1) for object B10:

  Save9begin
(property RHO1 at B10 is 1.0+0.1*TEM1+1.E-6*TEM1^2) 
  Save9end 

• Make density a quadratic function of temperature (TEM1) for material 123:

  Save9begin
(property RHO1 is 1.0+0.1*TEM1+1.E-6*TEM1^2 with imat=123) 
  Save9end 

• Set a time-dependent heat source:

Q = min(10000*t, 3.0E6) for t < 720

Q = max(3.0e6-13000*(t-720), 5000) for t> 720

The heat source will thus increase linearly with time for the first 720 seconds, to a peak of 3MW which is reached after 300 seconds and maintained until 720 seconds. After 720 seconds, the heat source reduces linearly with time until it reaches a minimum value of 5kW at 950 seconds.

  Save13begin
(source of tem1 at fire1 is min(1e4*tim,3.e6) with if(tim.le.720)!WHOL)
(source of tem1 at fire1 is max(3.e6-1.3e4*(tim-720),5e3) with if(tim.gt.720)!WHOL)
  Save13end

The condition !WHOL sets the source as a total source for the whole object. Without it, the source would be per unit volume.

Note that in the above examples the In-Form commands are enclosed in Save begin/end lines. These are crucial for the VR-Editor to locate the lines, present them for editing and write them back into the Q1 file.

There are many other examples to be found in the library. They can be found from the PHOENICS Commander by following 'Study special features', 'In-Form'.

The In-Form Editor

Because In-Form statements often require more than one line, a special In-Form-Editor module has been attached to the Virtual-Reality Editor in order to facilitate their creation, recognition and modification. There are 'In-Form' buttons on the relevant pages of the Main Menu. Clicking on them starts the In-Form Editor:

This can be used in insert new commands and modify or delete existing ones. It will automatically insert the begin / end lines.

Contents