Index

NAME

Field - base class for scalar fields

INCLUDE

include "Field.h"

SYNTAX

 class Field : public virtual HandleId
 {
 protected:
   Field (const char* fieldname = NULL);
   String fieldname;

   Handle(SpaceTimeScale) xt_scale;    // shared between many objects
   ScalarScale            field_scale; // particular scaling for this field

 public:
   virtual ~Field ();

   // can check if a general string name is valid as a fieldname:
   static  void checkAndSetFieldname (String& fieldname, const char* name);

   void setFieldname (const char* name);
   String getFieldname () const              { return fieldname; }
   bool hasFieldname () const;

   virtual bool     ok () const;
   virtual void minmax (NUMT& min, NUMT& max, GridWithPts* grid =NULL) const;

   virtual NUMT valueFEM (const FiniteElement& fe, real t = DUMMY);
   virtual NUMT valuePt  (const Ptv(real)& x, real t = DUMMY);
   virtual NUMT valueNode (int node, real t = DUMMY) const;

   virtual Ptv(NUMT) derivativePt (const Ptv(real)& x, real t = DUMMY);

   virtual void derivativeFEM (Ptv(NUMT)& d, const FiniteElement& fe,
                               real t = DUMMY);

   virtual void fill  (NUMT value);
   virtual void add   (NUMT value);
   virtual void mult  (NUMT value);
   virtual void apply (Func(NUMT) f);
   virtual void add   (Field& field, int power, NUMT front_factor);

   void attachScale (const SpaceTimeScale& xt_scale);
           ScalarScale& getFieldScale ();
   const   SpaceTimeScale& getSpaceTimeScale ();
   bool hasScaling ();  // is space-time or field scale set?
   bool isScaled ()  { return field_scale.is_scaled; }
   virtual Field& scale ();
   virtual Field& unscale ();


   virtual void  print (Os os) const;
   // reading/writing fields for simres format:
   virtual void  attach (Grid& grid);
   virtual Grid* getGridBase();
   virtual void  loadData (Is is);
   virtual void  unloadData (Os os) const;

   CLASS_INFO

   DEF_VIRTUAL_CAST(FieldPiWisConst)
   DEF_VIRTUAL_CAST(FieldWithPtValues)
   DEF_VIRTUAL_CAST(FieldConst)
   DEF_VIRTUAL_CAST(FieldFE)
   DEF_VIRTUAL_CAST(FieldLattice)
   DEF_VIRTUAL_CAST(FieldScatPt)
   DEF_VIRTUAL_CAST(FieldFunc)
 };

KEYWORDS

scalar field, base class

DESCRIPTION

The  class  represents  the base class for scalar fields. Various
subclasses implement finite  difference  fields,  finite  element
fields,  constant  fields,  function  fields  and so on. The main
functions define methods for evaluating the field.  With  a  Han­
dle(Field)  it  is  easy  to  program with a field (for example a
variable coeffient in a PDE) without knowing the particular  for­
mat, that is, whether the field is just a constant, or defined in
terms of an explicit function, or represented by  finite  element
basis  functions over a complicated grid etc. Together with class
FieldFormat, that reads the field format from a menu system,  the
Field abstraction results in simplified programming.

A  Field can be assigned a scaling. Both the field values and the
spatial and temporal domain can be given different scalings.  The
scaling  information  is  contained  in  a  SpaceTimeScale object
(which is common for perhaps all  fields  in  a  problem)  and  a
ScalarScale  object  which is used to scale the field values. The
ScalarScale object has a pointer  that  can  point  to  the  data
structure    data    stores    the   field   value(s).    Calling
ScalarScale::scale will then automatically scale the  field  val­
ues.  An "inverse" function unscale also exists.  For a pure user
of a field class, the virtual scale and unscale functions in  the
Field  hierarchy  can  be used directly.  An example of using the
scaling features in Diffpack is given in the man  page  of  class
ScalarScale.

For  the  programmer  of a field subclass it is important to note
that one must explicitly attach the  internal  field  value  data
structure  to the field_scale object before scaling/unscaling can
take place.  For the programmer of a subclass,  scale  must  call
the  field_scale.scale  function and perhaps a scale function for
the grid. Note that two calls to a scale function should have  no
effect,  the second call should automatically be ignored. Look at
scale and  unscale  functions  in,  e.g.,  class  FieldConst  and
FieldFE for examples.

Note that at present FieldFunc is not well supported for scaling.

CONSTRUCTORS AND INITIALIZATION

The constructor takes the fieldname as argument. Although it  can
be  omitted,  must  subclasses require the fieldname to be given.
The fieldname is used when dumping data to file (for later  visu­
alization) and in error messages.

MEMBER FUNCTIONS

setFieldname - sets the fieldname manually.

getFieldname - returns the fieldname as a String.

checkAndSetFieldname  - checks if a string name is a valid field­
name (which means that it must be a valid filename). If so,  name
is  assigned to fieldname. Otherwise, fieldname is set equal to a
dummy name Field_without_name (this is also the case if  name  is
NULL).

ok  -  returns  true  if  the object is initialized, for the base
class Field it just writes an error  messages  such  that  if   a
derived  class  fails  to define an ok function, an error message
will be written.

attach - attaches a grid to the field. Used  by  the  FieldReader
and  SimResFile  classes when reading fields from files. Specific
versions of the function are implemented in the subclasses.

minmax - finds the minimum and maximum values of the field.  Most
of  the  subclass  fields have an internal grid and will find the
extreme values  over  this  grid.  The  minmax  function  has  an
optional  argument  grid  that  can be supplied. This grid is not
used if the field has an internal grid.   However,  some  fields,
like  FieldFunc,  do not have internal grids and in that case the
grid argument is required in order to compute the extreme values.

valuePt  -  evaluates the field at a point in space and time. The
time argument can be omitted, the default value  is  then  DUMMY.
Generally,  we  suggest  to use DUMMY to check if fields are sta­
tionary.

valueFEM - evaluates the field at a point in space and time,  but
the argument is a FiniteElement object which means that the eval­
uation process in a finite element context will be very efficient
(since FiniteElement knows the element number and the local coor­
dinates of the spatial  point).   The  function  is  virtual  and
offers  a  unified  interface  to  the evaluation of all types of
fields in a finite element based simulator.

derivativePt - evaluates the derivative of the field at  a  point
in space and time.

fill - fills the field with a numerical value (that is, the field
becomes constant).

add - adds a constant field to the field.  An overloaded  version
takes  a Field f, an integer power i and a factor c as arguments.
The formula c*f^i is added to the object field.

mult - multiples the field values by a number.

apply - applies a function, like sin(x), to the field.

print - prints the field. Most subclass  implementations  involve
printing the field values and the grid.

attachScale  -  attaches a space-time scaling that applies to the
domain of the field.

getFieldScale - returns access  to  the  scaling  of  the  scalar
field.  To load an external scaling (represented by a ScalarScale
object) to a particular field, simply use the ScalarScale::opera­
tor= function by calling
field.getFieldScale()   =   myscale;   //  myscale  is  of  class
ScalarScale
Only  the  scaling  parameters  will  be  copied (not the name or
pointers  to  data  structures,  see  the  man  page   of   class
ScalarScale).

getSpaceTimeScale  -  returns access to the scaling of the domain
that applies to the field (if such a scaling has been attached by
the attach function).

hasScaling  -  returns  a  true  value if the field has a scaling
(either the field values or the space/time-domain is scaled).

scale - scale the field values and the space(-time) domain.  That
is,  the original values of the field are overwritten by the new,
scaled values.  To retrieve the original  values,  call  unscale.
Both scale and unscale tests a variable first to determine if the
field is already scaled or unscaled  (calling  e.g.  scale  twice
then results in no action of the second call).

unscale - the inverse action of scale.

unloadData  -  a  special print function that is used for dumping
the field to a SimRes file. (See classes  SimResFile  and  Field­
Writer).

loadData  -  a  special  scan function used for reading the field
from a SimRes file. (See classes SimResFile and FieldReader).

getGridBase - returns a Grid base class pointer to the grid asso­
ciated  with  the  field.  Since  many field types do not have an
associated grid, the function is not meaningful for  all  fields.
The getGridBase function is used by the SimResFile and FileReader
classes.

SEE ALSO

class Fields

DEVELOPED BY

SINTEF Applied Mathematics, Oslo, Norway, and University of Oslo,
Dept. of Mathematics, Norway

AUTHOR

Hans Petter Langtangen, SINTEF/UiO