Calculational and Utility

This section of the API manual describes some calculational and utility functions that can be used to compute things such as facelists or catentate an array of strings into a single string for simple output with DBWrite().

There are also functions to compute a DBmaterial object from dense volume fraction arrays and vice versa.

`DBCalcExternalFacelist()`

Summary: Calculate an external facelist for a UCD mesh.

C Signature:

DBfacelist *DBCalcExternalFacelist (int nodelist[], int nnodes,
    int origin, int shapesize[],
    int shapecnt[], int nshapes, int matlist[],
    int bnd_method)

Fortran Signature:

integer function dbcalcfl(nodelist, nnodes, origin, shapesize,
   shapecnt, nshapes, matlist, bnd_method, flid)

returns the pointer-id of the created object in flid.

Arguments:

Arg name	Description
`nodelist`	Array of node indices describing mesh zones.
`nnodes`	Number of nodes in associated mesh.
`origin`	Origin for indices in the `nodelist` array. Should be zero or one.
`shapesize`	Array of length `nshapes` containing the number of nodes used by each zone shape.
`shapecnt`	Array of length `nshapes` containing the number of zones having each shape.
`nshapes`	Number of zone shapes.
`matlist`	Array containing material numbers for each zone (else `NULL`).
`bnd_method`	Method to use for calculating external faces. See description below.

Returned value:

DBCalcExternalFacelist returns a DBfacelist pointer on success and NULL on failure.

Description:

The DBCalcExternalFacelist function calculates an external facelist from the zonelist and zone information describing a UCD mesh. The calculation of the external facelist is controlled by the bnd_method parameter as defined in the table below:

bnd_method	Meaning
0	Do not use material boundaries when computing external faces. The `matlist` parameter can be replaced with `NULL`.
1	In addition to true external faces, include faces on material boundaries between zones. Faces get generated for both zones sharing a common face. This setting should not be used with meshes that contain mixed material zones. If this setting is used with meshes with mixed material zones, all faces which border a mixed material zone will be include. The `matlist` parameter must be provided.

For a description of how the nodes for the allowed shapes are enumerated, see DBPutUcdmesh.

`DBCalcExternalFacelist2()`

Summary: Calculate an external facelist for a UCD mesh containing ghost zones.

C Signature:

DBfacelist *DBCalcExternalFacelist2 (int nodelist[], int nnodes,
    int low_offset, int hi_offset, int origin,
    int shapetype[], int shapesize[],
    int shapecnt[], int nshapes, int matlist[], int bnd_method)

Fortran Signature:
```
None
```

Arguments:

Arg name	Description
`nodelist`	Array of node indices describing mesh zones.
`nnodes`	Number of nodes in associated mesh.
`lo_offset`	The number of ghost zones at the beginning of the `nodelist`.
`hi_offset`	The number of ghost zones at the end of the `nodelist`.
`origin`	Origin for indices in the `nodelist` array. Should be zero or one.
`shapetype`	Array of length `nshapes` containing the type of each zone shape. See description below.
`shapesize`	Array of length `nshapes` containing the number of noes used by each zone shape.
`shapecnt`	Array of length `nshapes` containing the number of zones having each shape.
`nshapes`	Number of zone shapes.
`matlist`	Array containing material numbers for each zone (else `NULL`).
`bnd_method`	Method to use for calculating external faces. See description below.

Returned value:

DBCalcExternalFacelist2 returns a DBfacelist pointer on success and NULL on failure.

Description:

The DBCalcExternalFacelist2 function calculates an external facelist from the zonelist and zone information describing a UCD mesh. The calculation of the external facelist is controlled by the bnd_method parameter as defined in the table below:

bnd_method	Meaning
0	Do not use material boundaries when computing external faces. The `matlist` parameter can be replaced with `NULL`.
1	In addition to true external faces, include faces on material boundaries between zones. Faces get generated for both zones sharing a common face. This setting should not be used with meshes that contain mixed material zones. If this setting is used with meshes with mixed material zones, all faces which border a mixed material zone will be included. The `matlist` parameter must be provided.

The allowed shape types are described in the following table:

Type	Description
`DB_ZONETYPE_BEAM`	A line segment
`DB_ZONETYPE_POLYGON`	A polygon where nodes are enumerated to form a polygon
`DB_ZONETYPE_TRIANGLE`	A triangle
`DB_ZONETYPE_QUAD`	A quadrilateral
`DB_ZONETYPE_POLYHEDRON`	A polyhedron with nodes enumerated to form faces and faces are enumerated to form a polyhedron
`DB_ZONETYPE_TET`	A tetrahedron
`DB_ZONETYPE_PYRAMID`	A pyramid
`DB_ZONETYPE_PRISM`	A prism
`DB_ZONETYPE_HEX`	A hexahedron

For a description of how the nodes for the allowed shapes are enumerated, see DBPutUcdmesh.

`DBStringArrayToStringList()`

Summary: Utility to catentate a group of strings into a single, semi-colon delimited string.

C Signature:

void DBStringArrayToStringList(char const * const *strArray,
    int n, char **strList, int *m)

Fortran Signature:
```
None
```

Arguments:

Arg name	Description
`strArray`	Array of strings to catenate together. Note that it can be ok if some entries in `strArray` are the empty string, “” or `NULL` (0).
`n`	The number of entries in `strArray`. Passing -1 here indicates that the function should count entries in `strArray` until reaching the first `NULL` entry. In this case, embedded `NULL`s (0s) in `strArray` are, of course, not allowed.
`strList`	The returned catenated, semi-colon separated, single, string.
`m`	The returned length of `strList`.

Description:

This is a utility function to facilitate writing of an array of strings to a file. This function will take an array of strings and catenate them together into a single, semi-colon delimited list of strings.

Some characters are not permitted in the input strings. These are ‘\n’, ‘\0’ and ‘;’ characters.

This function can be used together with DBWrite() to easily write a list of strings to the a Silo database.

`DBStringListToStringArray()`

Summary: Given a single, semi-colon delimited string, de-catenate it into an array of strings.

C Signature:

char **DBStringListToStringArray(char *strList, int n,
    int handleSlashSwap, int skipFirstSemicolon)

Fortran Signature:
```
None
```

Arguments:

Arg name	Description
`strList`	A semi-colon separated, single string. Note that this string is modified by the call. If the caller doesn’t want this, it will have to make a copy before calling.
`n`	The expected number of individual strings in `strList`. Pass -1 here if you have no aprior knowledge of this number. Knowing the number saves an additional pass over `strList`.
`handleSlashSwap`	a boolean to indicate if slash characters should be swapped as per differences in windows/linux file systems.
`This is specific to Silo's internal handling of strings used in multi-block objects. So, you should pass zero (0) here.`	skipFirstSemicolon
`a boolean to indicate if the first semicolon in the string should be skipped.`	This is specific to Silo’s internal usage for legacy compatibility. You should pass zero (0) here.

Description:

This function performs the reverse of DBStringArrayToStringList.

`DBFreeStringArray()`

Summary: Free an array of strings

C Signature:

void DBFreeStringArray(char **strArray, int n)

Fortran Signature:
```
None
```

Arguments:

Arg Name	Description
`strArray`	the array of strings to be freed (some members can be `NULL`)
`n`	If `n>0`, `n` is the number of `char*` pointers in `strArray`. If `n<0`, `strArray` is treated as `NULL`-terminated. That is, entries in `strArray` are freed until the first `NULL` entry is encountered.

Returned value:

void
Description:

This function simplifies freeing of an array of strings constructed from DBStringListToStringArray. If n>0, if strArray contains NULL entries, it will handle this condition. If n<0, strArray is treated as NULL-terminated. That is, entries in strArray are freed until the first NULL entry is encountered.

`DBAnnotateUcdmesh()`

Summary: Walk a UCD mesh guessing and adding shapetype info
C Signature:
```
int DBAnnotateUcdmesh(DBucdmesh *m)
```
Fortran Signature:
```
None
```
Arguments:

Arg Name

Description

m

A pointer to a DBucdmesh object
Returned value:

Returns 1 when one or more zones/shapes were annotated and 0 if not annotation was performed. Returns -1 if an error occurred.
Description:

Walks a DBucdmesh data structure and guesses and adds shapetype info based on ndims and shapesizes and node counts of the individual shapes. This is useful for taking an old-style DBZonelist object which did not include the shapetype member populating it based on some simple heuristics.

`DBJoinPath()`

Summary: Join two strings representing paths into a single path

C Signature:

char * DBJoinPath(char const *first, char const *second)

Fortran Signature:
```
None
```
Arguments:

Arg Name

Description

first

The first path relative to which the second path will be joined

second

The second path to be combined into the first.
Returned value:

The joined path string or NULL if an error occured. The caller should free() the string.

Description:

The goal of this method is to take an existing string representing a path and a second string representing another path relative to the first path and then combine them into a single path.

Input	Result
`DBJoinPath("foo","bar")`	`"foo/bar"`
`DBJoinPath("foo","./bar")`	`"foo/bar"`
`DBJoinPath("foo","../bar")`	`"bar"`
`DBJoinPath("foo","/bar")`	`"/bar"`
`DBJoinPath("/foo","/bar")`	`"/bar"`
`DBJoinPath("/foo","../bar")`	`"/bar"`
`DBJoinPath("foo/bar/baz","../../bin")`	`"foo/bin"`
`DBJoinPath("foo/bar/baz",".././/..//bin")`	`"foo/bin"`

`DBIsDifferentDouble()`

Summary: Compare doubles within absolute or relative tolerance

C Signature:

int DBIsDifferentDouble(double a, double b, double abstol,
        double reltol, double reltol_eps)

Fortran Signature:
```
None
```

Arguments:

Arg Name	Description
`a`	First double to compare
`b`	Second double to compare
`abstol`	Tolerance to be used for absolute difference. Set to a negative value to ignore this tolerance.
`reltol`	Tolerance to be used for relative difference. Set to a negative value to ignore this tolerance.
`reltol_eps`	Epsilon value to be used in alternative relative tolerance difference. Set to a negative value to ignore this.

Returned value:

0 if the difference between a and b is below tolerance. Otherwise 1. This cannot fail

Description:

Determines if a and b are the same or different based on an absolute or relative tolerances passed in. Its easies to see how the function behaves by having a look at the actual code…

int DBIsDifferentDouble(double a, double b, double abstol, double reltol, double reltol_eps)
{
   double       num, den;

   /* handle possible NaNs first */
   if (isnan(a))
   {
       if (isnan(b)) return 0;
       return 1;
   }
   else if (isnan(b))
   {
       return 1;
   }

   /*
    * First, see if we should use the alternate diff.
    * check |A-B|/(|A|+|B|+EPS) in a way that won't overflow.
    */
   if (reltol_eps >= 0 && reltol > 0)
   {
      if ((a<0 && b>0) || (b<0 && a>0)) {
         num = fabs (a/2 - b/2);
         den = fabs (a/2) + fabs(b/2) + reltol_eps/2;
         reltol /= 2;
      } else {
         num = fabs (a - b);
         den = fabs (a) + fabs(b) + reltol_eps;
      }
      if (0.0==den && num) return 1;
      if (num/den > reltol) return 1;
      return 0;
   }
   else /* use the old Abs|Rel difference test */
   {
      /*
       * Now the |A-B| but make sure it doesn't overflow which can only
       * happen if one is negative and the other is positive.
       */
      if (abstol>0) {
         if ((a<0 && b>0) || (b<0 && a>0)) {
            if (fabs (a/2 - b/2) > abstol/2) return 1;
         } else {
            if (fabs(a-b) > abstol) return 1;
         }
      }

      /*
       * Now check 2|A-B|/|A+B| in a way that won't overflow.
       */
      if (reltol>0) {
         if ((a<0 && b>0) || (b<0 && a>0)) {
            num = fabs (a/2 - b/2);
            den = fabs (a/2 + b/2);
            reltol /= 2;
         } else {
            num = fabs (a - b);
            den = fabs (a/2 + b/2);
         }
         if (0.0==den && num) return 1;
         if (num/den > reltol) return 1;
      }

      if (abstol>0 || reltol>0) return 0;
   }

   /*
    * Otherwise do a normal exact comparison.
    */
   return a!=b;

`DBIsDifferentLongLong()`

Summary: Compare long longs within absolute or relative tolerance

C Signature:

int DBIsDifferentLongLong(long long a, long long b, double abstol,
        double reltol, double reltol_eps);

Fortran Signature:
```
None
```

Arguments:

Arg Name	Description
`a`	First long long to compare
`b`	Second long long to compare
`abstol`	Tolerance to be used for absolute difference. Set to a negative value to ignore this tolerance.
`reltol`	Tolerance to be used for relative difference. Set to a negative value to ignore this tolerance.
`reltol_eps`	Epsilon value to be used in alternative relative tolerance difference. Set to a negative value to ignore this.

Returned value:

0 if the difference between a and b is below tolerance. Otherwise 1. This cannot fail
Description:

Same as DBIsDifferentDouble() except for long long type.

`DBCalcDenseArraysFromMaterial()`

Summary: Compute dense material volume fraction arrays from a DBmaterial object

C Signature:

int DBCalcDenseArraysFromMaterial(DBmaterial const *mat, int datatype,
        int *narrs, void ***vfracs);

Fortran Signature:
```
None
```

Arguments:

Arg Name	Description
`mat`	Input `DBmaterial` object
`datatype`	Desired data type (`DB_FLOAT` or `DB_DOUBLE`) of returned `vfracs` arrays.
`narrs`	Returned number of `vfracs` arrays
`vfracs`	Allocated and returned array of volume fractions for each material.

Returned value:

0 on successful completion. -1 if an error is encountered.
Description:

Traverse a Silo DBmaterial object and return a collection of dense, DB_ZONECENTERED volume fraction arrays, one array of volume fractions for each material. The order of the arrays in the returned vfracs is one-to-one with the order of the matnos member of the DBmaterial object. The order of zone-centered volume fractions in any given vfracs[i] array is one-to-one with matlist member of the DBmaterial obje ct.

The representation is dense because there is a float (or double) for every zone and every material. Even when a zone is clean in a material, the representation stores a 1 for the associated vfracs entry and 0’s for all other entries.

`DBCalcMaterialFromDenseArrays()`

Summary: Build a DBmaterial object from dense volume fraction arrays

C Signature:

DBmaterial *DBCalcMaterialFromDenseArrays(int narrs, int ndims, int const *dims,
               int const *matnos, int dtype, DBVCP2_t const vfracs)

Fortran Signature:
```
None
```

Arguments:

Arg Name	Description
`narrs`	the number of volume fraction arrays in `vfracs`
`ndims`	the number of dimensions in the `vfracs` arrays
`dims`	the size in each dimension of the `vfracs` arrays
`matnos`	the material numbers
`dtype`	the datatype of the `vfracs` arrays (either `DB_FLOAT` or `DB_DOUBLE`)
`vfracs`	the dense volume fraction arrays

Returned value:

A DBmaterial object holding equivalent volume fraction information of the arrays or NULL if an error occurred.
Description:

Performs the reverse operation of DBCalcDenseArraysFromMaterial. Often, the DBmaterial representation is a much more efficient storage format and requires far less memory.

Calculational and Utility

DBCalcExternalFacelist()

DBCalcExternalFacelist2()

DBStringArrayToStringList()

DBStringListToStringArray()

DBFreeStringArray()

DBAnnotateUcdmesh()

DBJoinPath()

DBIsDifferentDouble()

DBIsDifferentLongLong()

DBCalcDenseArraysFromMaterial()

DBCalcMaterialFromDenseArrays()

`DBCalcExternalFacelist()`

`DBCalcExternalFacelist2()`

`DBStringArrayToStringList()`

`DBStringListToStringArray()`

`DBFreeStringArray()`

`DBAnnotateUcdmesh()`

`DBJoinPath()`

`DBIsDifferentDouble()`

`DBIsDifferentLongLong()`

`DBCalcDenseArraysFromMaterial()`

`DBCalcMaterialFromDenseArrays()`