esys.modellib.visualization Package — esys.escript 5.6 documentation

# esys.modellib.visualization Package

## Classes

- `Data`
- `Link`
- `Model`
- `Visualization`
- `WriteVTK`

class `esys.modellib.visualization.` `Data`

  Bases: `Boost.Python.instance`

  Represents a collection of datapoints. It is used to store the values of a function. For more details please consult the c++ class documentation.

  `__init__`((object)arg1) → None

    __init__( (object)arg1, (object)value [, (object)p2 [, (object)p3 [, (object)p4]]]) -> None

  `conjugate`((Data)arg1) → Data
  `copy`((Data)arg1, (Data)other) → None :

    Make this object a copy of `other`

    > note: | The two objects will act independently from now on. That is, changing `other` after this call will not change this object and vice versa.

    copy( (Data)arg1) -> Data :

      note: | In the no argument form, a new object will be returned which is an independent copy of this object.

  `copyWithMask`((Data)arg1, (Data)other, (Data)mask) → None :

    Selectively copy values from `other` `Data`.Datapoints which correspond to positive values in `mask` will be copied from `other`

    Parameters: | other (`Data`) – source of values mask (Scalar `Data`) –

  `delay`((Data)arg1) → Data :

    Convert this object into lazy representation

  `dump`((Data)arg1, (str)fileName) → None :

    Save the data as a netCDF file

    Parameters: | fileName (`string`) –

  `expand`((Data)arg1) → None :

    Convert the data to expanded representation if it is not expanded already.

  `getDomain`((Data)arg1) → Domain :

    Return type: | `Domain`

  `getFunctionSpace`((Data)arg1) → FunctionSpace :

    Return type: | `FunctionSpace`

  `getNumberOfDataPoints`((Data)arg1) → int :

    Return type: | `int`
    Returns: | Number of datapoints in the object

  `getRank`((Data)arg1) → int :

    Returns: | the number of indices required to address a component of a datapoint
    Return type: | positive `int`

  `getShape`((Data)arg1) → tuple :

    Returns the shape of the datapoints in this object as a python tuple. Scalar data has the shape `()`

    Return type: | `tuple`

  `getTagNumber`((Data)arg1, (int)dpno) → int :

    Return tag number for the specified datapoint

    Return type: | int
    Parameters: | dpno (int) – datapoint number

  `getTupleForDataPoint`((Data)arg1, (int)dataPointNo) → object :

    Returns: | Value of the specified datapoint
    Return type: | `tuple`
    Parameters: | dataPointNo (`int`) – datapoint to access

  `getTupleForGlobalDataPoint`((Data)arg1, (int)procNo, (int)dataPointNo) → object :

    Get a specific datapoint from a specific process

    Return type: | `tuple`
    Parameters: | procNo (positive `int`) – MPI rank of the process dataPointNo (int) – datapoint to access

  `getX`((Data)arg1) → Data :

    Returns the spatial coordinates of the spatial nodes. :rtype: `Data`

  `hasInf`((Data)arg1) → bool :

    Returns return true if data contains +-Inf. [Note that for complex values, hasNaN and hasInf are not mutually exclusive.]

  `hasNaN`((Data)arg1) → bool :

    Returns return true if data contains NaN. [Note that for complex values, hasNaN and hasInf are not mutually exclusive.]

  `imag`((Data)arg1) → Data
  `internal_maxGlobalDataPoint`((Data)arg1) → tuple :

    Please consider using getSupLocator() from pdetools instead.

  `internal_minGlobalDataPoint`((Data)arg1) → tuple :

    Please consider using getInfLocator() from pdetools instead.

  `interpolate`((Data)arg1, (FunctionSpace)functionspace) → Data :

    Interpolate this object’s values into a new functionspace.

  `interpolateTable`((Data)arg1, (object)table, (float)Amin, (float)Astep, (Data)B, (float)Bmin, (float)Bstep[, (float)undef=1e+50[, (bool)check_boundaries=False]]) → Data :
    Creates a new Data object by interpolating using the source data (which are

      looked up in `table`) `A` must be the outer dimension on the table

      param table: | two dimensional collection of values
      param Amin: | The base of locations in table
      type Amin: | float
      param Astep: | size of gap between each item in the table
      type Astep: | float
      param undef: | upper bound on interpolated values
      type undef: | float
      param B: | Scalar representing the second coordinate to be mapped into the table
      type B: | `Data`
      param Bmin: | The base of locations in table for 2nd dimension
      type Bmin: | float
      param Bstep: | size of gap between each item in the table for 2nd dimension
      type Bstep: | float
      param check_boundaries:
      | if true, then values outside the boundaries will be rejected. If false, then boundary values will be used.
      raise RuntimeError(DataException):
      | if the coordinates do not map into the table or if the interpolated value is above `undef`
      rtype: | `Data`

    interpolateTable( (Data)arg1, (object)table, (float)Amin, (float)Astep [, (float)undef=1e+50 [, (bool)check_boundaries=False]]) -> Data

  `isComplex`((Data)arg1) → bool :

    Return type: | `bool`
    Returns: | True if this `Data` stores complex values.

  `isConstant`((Data)arg1) → bool :

    Return type: | `bool`
    Returns: | True if this `Data` is an instance of `DataConstant`
    Note: | This does not mean the data is immutable.

  `isEmpty`((Data)arg1) → bool :

    Is this object an instance of `DataEmpty`

    Return type: | `bool`
    Note: | This is not the same thing as asking if the object contains datapoints.

  `isExpanded`((Data)arg1) → bool :

    Return type: | `bool`
    Returns: | True if this `Data` is expanded.

  `isLazy`((Data)arg1) → bool :

    Return type: | `bool`
    Returns: | True if this `Data` is lazy.

  `isProtected`((Data)arg1) → bool :

    Can this instance be modified. :rtype: `bool`

  `isReady`((Data)arg1) → bool :

    Return type: | `bool`
    Returns: | True if this `Data` is not lazy.

  `isTagged`((Data)arg1) → bool :

    Return type: | `bool`
    Returns: | True if this `Data` is expanded.

  `nonuniformInterpolate`((Data)arg1, (object)in, (object)out, (bool)check_boundaries) → Data :

    1D interpolation with non equally spaced points

  `nonuniformSlope`((Data)arg1, (object)in, (object)out, (bool)check_boundaries) → Data :

    1D interpolation of slope with non equally spaced points

  `phase`((Data)arg1) → Data
  `promote`((Data)arg1) → None
  `real`((Data)arg1) → Data
  `replaceInf`((Data)arg1, (object)value) → None :

    Replaces +-Inf values with value. [Note, for complex Data, both real and imaginary components are replaced even if only one part is Inf].

  `replaceNaN`((Data)arg1, (object)value) → None :

    Replaces NaN values with value. [Note, for complex Data, both real and imaginary components are replaced even if only one part is NaN].

  `resolve`((Data)arg1) → None :

    Convert the data to non-lazy representation.

  `setProtection`((Data)arg1) → None :

    Disallow modifications to this data object

    Note: | This method does not allow you to undo protection.

  `setTaggedValue`((Data)arg1, (int)tagKey, (object)value) → None :

    Set the value of tagged Data.

    > param tagKey: | tag to update
    > type tagKey: | `int`

    setTaggedValue( (Data)arg1, (str)name, (object)value) -> None :

      param name: | tag to update
      type name: | `string`
      param value: | value to set tagged data to
      type value: | `object` which acts like an array, `tuple` or `list`

  `setToZero`((Data)arg1) → None :

    After this call the object will store values of the same shape as before but all components will be zero.

  `setValueOfDataPoint`((Data)arg1, (int)dataPointNo, (object)value) → None

    setValueOfDataPoint( (Data)arg1, (int)arg2, (object)arg3) -> None

    setValueOfDataPoint( (Data)arg1, (int)arg2, (float)arg3) -> None :

    > Modify the value of a single datapoint.

    > param dataPointNo:
    > type dataPointNo:
    > | int
    > param value: |
    > type value: | `float` or an object which acts like an array, `tuple` or `list`
    > warning: | Use of this operation is discouraged. It prevents some optimisations from operating.

  `tag`((Data)arg1) → None :

    Convert data to tagged representation if it is not already tagged or expanded

  `toListOfTuples`((Data)arg1[, (bool)scalarastuple=False]) → object :

    Return the datapoints of this object in a list. Each datapoint is stored as a tuple.

    Parameters: | scalarastuple – if True, scalar data will be wrapped as a tuple. True => [(0), (1), (2)]; False => [0, 1, 2]

class `esys.modellib.visualization.` `Link`(target, attribute=None)

  Bases: `object`

  A Link makes an attribute of an object callable:

      o.object()
      o.a=8
      l=Link(o,"a")
      assert l()==8

  `__init__`(target, attribute=None)

    Creates a link to the object target. If attribute is given, the link is established to this attribute of the target. Otherwise the attribute is undefined.

  classmethod `fromDom`(esysxml, node)
  `getAttributeName`()

    Returns the name of the attribute the link is pointing to.

  `getTarget`()

    Returns the target.

  `hasDefinedAttributeName`()

    Returns true if an attribute name is set.

  `setAttributeName`(attribute)

    Sets a new attribute name to be collected from the target object. The target object must have the attribute with name attribute.

  `toDom`(esysxml, node)

    `toDom` method of Link. Creates a Link node and appends it to the current XML esysxml.

class `esys.modellib.visualization.` `Model`(parameters=[], **kwargs)

  Bases: `esys.escriptcore.modelframe.ParameterSet`

  A Model object represents a process marching over time until a finalizing condition is fulfilled. At each time step an iterative process can be performed and the time step size can be controlled. A Model has the following work flow:

      doInitialization()
      while not terminateInitialIteration(): doInitialStep()
      doInitialPostprocessing()
      while not finalize():
          dt=getSafeTimeStepSize(dt)
          doStepPreprocessing(dt)
          while not terminateIteration(): doStep(dt)
          doStepPostprocessing(dt)
      doFinalization()

  where `doInitialization`, `finalize`, `getSafeTimeStepSize`, `doStepPreprocessing`, `terminateIteration`, `doStepPostprocessing`, `doFinalization` are methods of the particular instance of a Model. The default implementations of these methods have to be overwritten by the subclass implementing a Model.

  `__init__`(parameters=[], **kwargs)

    Creates a model.

    Just calls the parent constructor.

  `UNDEF_DT` = 1e+300
  `checkLinkTargets`(models, hash)

    Returns a set of tuples (“<self>(<name>)”, <target model>) if the parameter <name> is linked to model <target model> but <target model> is not in the list of models. If a parameter is linked to another parameter set which is not in the hash list the parameter set is checked for its models. hash gives the call history.

  `declareParameter`(**parameters)

    Declares one or more new parameters and their initial value.

  `declareParameters`(parameters)

    Declares a set of parameters. parameters can be a list, a dictionary or a ParameterSet.

  `doFinalization`()

    Finalizes the time stepping.

    This function may be overwritten.

  `doInitialPostprocessing`()

    Finalises the initialization iteration process. This method is not called in case of a restart.

    This function may be overwritten.

  `doInitialStep`()

    Performs an iteration step in the initialization phase. This method is not called in case of a restart.

    This function may be overwritten.

  `doInitialization`()

    Initializes the time stepping scheme. This method is not called in case of a restart.

    This function may be overwritten.

  `doStep`(dt)

    Executes an iteration step at a time step.

    `dt` is the currently used time step size.

    This function may be overwritten.

  `doStepPostprocessing`(dt)

    Finalises the time step.

    dt is the currently used time step size.

    This function may be overwritten.

  `doStepPreprocessing`(dt)

    Sets up a time step of step size dt.

    This function may be overwritten.

  `finalize`()

    Returns False if the time stepping is finalized.

    This function may be overwritten.

  classmethod `fromDom`(esysxml, node)
  `getAttributeObject`(name)

    Returns the object stored for attribute `name`.

  `getSafeTimeStepSize`(dt)

    Returns a time step size which can be safely used.

    `dt` gives the previously used step size.

    This function may be overwritten.

  `hasAttribute`(name)

    Returns True if self has attribute `name`.

  `releaseParameters`(name)

    Removes parameter name from the parameters.

  `setUp`()

    Sets up the model.

    This function may be overwritten.

  `showParameters`()

    Returns a description of the parameters.

  `terminateInitialIteration`()

    Returns True if iteration at the inital phase is terminated.

  `terminateIteration`()

    Returns True if iteration on a time step is terminated.

  `toDom`(esysxml, node)

    `toDom` method of Model class.

  `trace`(msg)

    If debugging is on, prints the message, otherwise does nothing.

  `writeXML`(ostream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

    Writes the object as an XML object into an output stream.

class `esys.modellib.visualization.` `Visualization`(**kwargs)

  Bases: `esys.escriptcore.modelframe.Model`

  Generic visualization Model

  Variables: | t – current time (in) n – frame counter (in) dt – increment for output (in) filename – name of the output file (in)

  `__init__`(**kwargs)

    Initialisation of the visualisation model object

    Parameters: | debug – Debugging flag

  `UNDEF_DT` = 1e+300
  `checkLinkTargets`(models, hash)

    Returns a set of tuples (“<self>(<name>)”, <target model>) if the parameter <name> is linked to model <target model> but <target model> is not in the list of models. If a parameter is linked to another parameter set which is not in the hash list the parameter set is checked for its models. hash gives the call history.

  `declareParameter`(**parameters)

    Declares one or more new parameters and their initial value.

  `declareParameters`(parameters)

    Declares a set of parameters. parameters can be a list, a dictionary or a ParameterSet.

  `doFinalization`()

    Finalizes the time stepping.

    This function may be overwritten.

  `doInitialPostprocessing`()

    Finalises the initialization iteration process. This method is not called in case of a restart.

    This function may be overwritten.

  `doInitialStep`()

    Performs an iteration step in the initialization phase. This method is not called in case of a restart.

    This function may be overwritten.

  `doInitialization`()

    does some kind of initialisation

  `doStep`(dt)

    Executes an iteration step at a time step.

    `dt` is the currently used time step size.

    This function may be overwritten.

  `doStepPostprocessing`(dt)

    Finalises the time step.

    dt is the currently used time step size.

    This function may be overwritten.

  `doStepPreprocessing`(dt)

    Sets up a time step of step size dt.

    This function may be overwritten.

  `finalize`()

    Returns False if the time stepping is finalized.

    This function may be overwritten.

  classmethod `fromDom`(esysxml, node)
  `getAttributeObject`(name)

    Returns the object stored for attribute `name`.

  `getFrameCounter`()

    returns a frame counter

  `getFrameFileName`()
  `getSafeTimeStepSize`(dt)

    returns new step size

    Parameters: | dt (`float`) – last time step size used
    Returns: | time step size that can savely be used
    Return type: | `float`

  `hasAttribute`(name)

    Returns True if self has attribute `name`.

  `releaseParameters`(name)

    Removes parameter name from the parameters.

  `setUp`()

    Sets up the model.

    This function may be overwritten.

  `showParameters`()

    Returns a description of the parameters.

  `terminateInitialIteration`()

    Returns True if iteration at the inital phase is terminated.

  `terminateIteration`()

    Returns True if iteration on a time step is terminated.

  `toDom`(esysxml, node)

    `toDom` method of Model class.

  `trace`(msg)

    If debugging is on, prints the message, otherwise does nothing.

  `writeFrame`()

    returns True if the time stamp for writing frame is reached.

  `writeXML`(ostream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

    Writes the object as an XML object into an output stream.

class `esys.modellib.visualization.` `WriteVTK`(**kwargs)

  Bases: `esys.modellib.visualization.Visualization`

  Writes data into a VTK file.

  The Model can handel up to 20 data sets that are written into a single file tagged with the given name. If no name is given and the data are defined by a `Link` the name of the target attribute is used as a tag.

  Variables: | data0 – data set 0 to be written name0 – name tag for data set 0 data1 – data set 1 to be written name1 – name tag for data set 1 data2 – data set 2 to be written name2 – name tag for data set 2 data3 – data set 3 to be written name3 – name tag for data set 3 data4 – data set 4 to be written name4 – name tag for data set 4 data5 – data set 5 to be written name5 – name tag for data set 5 data6 – data set 6 to be written name6 – name tag for data set 6 data7 – data set 7 to be written name7 – name tag for data set 7 data8 – data set 8 to be written name8 – name tag for data set 8 data9 – data set 9 to be written name9 – name tag for data set 9 data10 – data set 10 to be written name10 – name tag for data set 10 data11 – data set 11 to be written name11 – name tag for data set 11 data12 – data set 12 to be written name12 – name tag for data set 12 data13 – data set 13 to be written name13 – name tag for data set 13 data14 – data set 14 to be written name14 – name tag for data set 14 data15 – data set 15 to be written name15 – name tag for data set 15 data16 – data set 16 to be written name16 – name tag for data set 16 data17 – data set 17 to be written name17 – name tag for data set 17 data18 – data set 18 to be written name18 – name tag for data set 18 data19 – data set 19 to be written name19 – name tag for data set 19

  `__init__`(**kwargs)

    Initialisation of the WriteVTK object

    Parameters: | debug (`bool`) – debugging flag

  `UNDEF_DT` = 1e+300
  `checkLinkTargets`(models, hash)

    Returns a set of tuples (“<self>(<name>)”, <target model>) if the parameter <name> is linked to model <target model> but <target model> is not in the list of models. If a parameter is linked to another parameter set which is not in the hash list the parameter set is checked for its models. hash gives the call history.

  `collectData`()
  `declareParameter`(**parameters)

    Declares one or more new parameters and their initial value.

  `declareParameters`(parameters)

    Declares a set of parameters. parameters can be a list, a dictionary or a ParameterSet.

  `doFinalization`()

    Finalizes the time stepping.

    This function may be overwritten.

  `doInitialPostprocessing`()

    writes vtk file at the end of initial iteration

  `doInitialStep`()

    Performs an iteration step in the initialization phase. This method is not called in case of a restart.

    This function may be overwritten.

  `doInitialization`()

    does some kind of initialisation

  `doStep`(dt)

    Executes an iteration step at a time step.

    `dt` is the currently used time step size.

    This function may be overwritten.

  `doStepPostprocessing`(dt)

    writes vtk file at the end of time iteration

  `doStepPreprocessing`(dt)

    Sets up a time step of step size dt.

    This function may be overwritten.

  `finalize`()

    Returns False if the time stepping is finalized.

    This function may be overwritten.

  classmethod `fromDom`(esysxml, node)
  `getAttributeObject`(name)

    Returns the object stored for attribute `name`.

  `getFrameCounter`()

    returns a frame counter

  `getFrameFileName`()
  `getSafeTimeStepSize`(dt)

    returns new step size

    Parameters: | dt (`float`) – last time step size used
    Returns: | time step size that can savely be used
    Return type: | `float`

  `hasAttribute`(name)

    Returns True if self has attribute `name`.

  `releaseParameters`(name)

    Removes parameter name from the parameters.

  `setUp`()

    Sets up the model.

    This function may be overwritten.

  `showParameters`()

    Returns a description of the parameters.

  `terminateInitialIteration`()

    Returns True if iteration at the inital phase is terminated.

  `terminateIteration`()

    Returns True if iteration on a time step is terminated.

  `toDom`(esysxml, node)

    `toDom` method of Model class.

  `trace`(msg)

    If debugging is on, prints the message, otherwise does nothing.

  `writeFrame`()

    returns True if the time stamp for writing frame is reached.

  `writeXML`(ostream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

    Writes the object as an XML object into an output stream.

## Functions

`esys.modellib.visualization.` `saveVTK`(filename, domain=None, metadata='', metadata_schema=None, write_meshdata=False, time=0.0, cycle=0, **data)

  Writes `Data` objects and their mesh to a file using the VTK XML file format.

  Example:

      temp=Scalar(..)
      v=Vector(..)
      saveVTK("solution.vtu", temperature=temp, velocity=v)

  `temp` and `v` are written to “solution.vtu” where `temp` is named “temperature” and `v` is named “velocity”.

  Meta tags, e.g. a timeStamp, can be added to the file, for instance:

      tmp=Scalar(..)
      v=Vector(..)
      saveVTK("solution.vtu", temperature=tmp, velocity=v,
              metadata="<timeStamp>1.234</timeStamp>",
              metadata_schema={"gml":"http://www.opengis.net/gml"})

  The argument `metadata_schema` allows the definition of name spaces with a schema used in the definition of meta tags.

  Parameters: | filename (`str`) – name of the output file (‘.vtu’ is added if required) domain (`escript.Domain`) – domain of the `Data` objects. If not specified, the domain of the given `Data` objects is used. <name> – writes the assigned value to the VTK file using <name> as identifier metadata (`str`) – additional XML meta data which are inserted into the VTK file. The meta data are marked by the tag `<MetaData>`. metadata_schema (`dict` with `metadata_schema[<namespace>]=<URI>` to assign the scheme `<URI>` to the name space `<namespace>`.) – assigns schemas to namespaces which have been used to define meta data. write_meshdata (`bool`) – whether to save mesh-related data such as element identifiers, ownership etc. This is mainly useful for debugging. time (`float`) – the timestamp to save within the file, seperate to metadata cycle (`int`) – the cycle (or timestep) of the data
  Note: | All data objects have to be defined on the same domain. They may not be in the same `FunctionSpace` but not all combinations of `FunctionSpace` s can be written to a single VTK file. Typically, data on the boundary and on the interior cannot be mixed.

## Others

## Packages