SCIRun Modules

Bundle

ChangeFieldData

CalculateDistanceToFieldBoundary

This module calculates a new value for each value in the Field data based on a user defined function. This function is based on a series of variables that is available for each data location. Once the function is defined, the module will walk through each data value and apply the function.

Detailed Description

This module allows the computation of a new scalar, vector or tensor value for each data location in the Field. The user defined function can depend on a number of variables that are defined for each location:

Input Variables

DATA: This is the current value stored in the Field (either on the element or the node location).
X,Y,Z: Cartesian coordinates of the node or element (center of the element)
POS: Vector with Cartesian coordinates of the node or element
A,B,C,...: Input from additional Matrix ports. The input Matrix can have either 1 row or the same number of rows as there are values in the Field. In case the Matrix has one value this value is the same for each data location, in case it has multiple values the module iterates of the values in the same way it iterates over the data values of the Field. The Matrix input can have either 1 column, 3 columns, 6 or 9 columns. In case the Matrix has 1 column values are assumed to be scalar values, in case the Matrix has 3 columns it is assumed to contain vector values and in case it has either 6 or 9 columns it is assumed to be a tensor value. A 6 valued tensor is defined as xx, xy, xz, yy, yz, and zz.
INDEX: The index number of the element or node.
SIZE: The number of elements or nodes in the Field (depends on the input Field mesh type).
ELEMENT: Special access variable to access properties of the element. Currently only length, area, and volume are available to be called on this entity. In case one is iterating over the nodes, the node point is assumed to be the element, in case one is iterating of the elements, this variable is referring to the full element.

Output Variable

The output needs to be stored in the variable RESULT.

Available Functions

A list of available functions is available in the GUI of the module. The Parser Help button brings up a list of available functions to do scalar/vector/tensor algebra and to view the functions that can be applied to the ELEMENT variable.

Input Ports

The first input is the Field whose data needs to be recalculated using a function. The second port is an optional port that allows the user to script the module with a user defined input function. This function will override the function entered in module GUI. The third and next ports are used to import a Matrix. The first port corresponds to Matrix A, the next to Matrix B and so on. These ports can be used to do algebra with values stored as a Matrix or can be used to enter scriptable scalar/vector/tensor values that can be defined elsewhere.

Output Port

The module has one output port that has the newly defined values.

Example Functions

Suppose one wants to set the data values to a certain value:

RESULT = 2;

This will set every data value inside the Field equal to the value 2.

Similarly one can set the data value to a value specified inside the first Matrix on the input ports:

RESULT = A;

If the Matrix contains only one value each data point is set to that value, if it contains the same number of values as datalocations, it will map each value in the Matrix to one value in the Field.

One can as well query the positions of the data point:

RESULT = X+Y;

This will store X+Y in each data location.

This same module can be used as well to generate vector or tensor data:

RESULT = Vector(X,Y,cos(A));

This will take the X, Y, position and the cos applied to the values in the Matrix A to create a new vector.

One can reuse the value that are there as well:

RESULT = DATA+A+B*C;

Output Data Type

As the function is parsed using the compiler, the output type cannot be guessed by the module, hence it needs to be set by the user to the correct data type.

Top

CalculateGradients

CalculateInsideWhichField

CalculateSignedDistanceToField

CalculateVectorMagnitudes

ConvertFieldBasis

ConvertFieldDataType

ConvertIndicesToFieldData

CreateFieldData

This module calculates a new value for each value in the field data based on a user defined function. This function is based on a series of variables that is available for each data location. Once the function is defined, the module will walk through each data value and apply the function.

Detailed Description

This module allows the computation of a new scalar, vector or tensor value for each data location in the field. This module is closely related to CalculateFieldData, however it does not require any data to be present in the field and the data already in the field is ignored. This module also allows the user to state whether he or she wants to calculate data at the elements or at the nodes of the mesh.

The user defined function can depend on a number of variables that are defined for each location:

Input Variables

X,Y,Z: Cartesian coordinates of the node or element (center of the element)
POS: Vector with cartesian coordinates of the node or element
A,B,C,...: Input from additional matrix ports. The input matrix can have either 1 row or the same number of rows as there are values in the field. In case the matrix has one value this value is the same for each data location, in case it has multiple values the module iterates of the values in the same way it iterates over the data values of the field. The matrix input can have either 1 column, 3 columns, 6 or 9 columns. In case the matrix has 1 column values are assumed to be scalar values, in case the matrix has 3 columns it is assumed to contain vector values and in case it has either 6 or 9 columns it is assumed to be a tensor value (A 6 valued tensor is defined as xx, xy, xz, yy, yz, and zz).
INDEX: The index number of the element or node.
SIZE: The number of elements or nodes in the field. (Depending on the input field type)
ELEMENT: Special access variable to access properties of the element. Currently only length, area, and volume are available to be called on this entity. In case one is iterating over the nodes, the node point is assumed to be the element, in case one is iterating of the elements, this variable is referring to the full element.

Output Variable

The output needs to be stored in the variable RESULT.

Available Functions

A list of available functions is available in the GUI of the module. Press on the button available functions to obtain a full overview of the current available functions to do Scalar/Vector/Tensor algebra and to view the functions that can be applied to the ELEMENT variable.

Input Ports

The first input is the field whose data needs to be recalculated using a function. The second port is an optional port that allows the user to script the module with a user defined input function. This function will override the function given in the GUI of the module. The third and next ports are used to import a matrix. The first port corresponds to matrix A, the next to matrix B and so on. These ports can be used to do algebra with values stored as a matrix or can be used to enter scriptable scalar/vector/tensor values that can be defined elsewhere.

Output Port

The module has one output port that has the newly defined values.

Output Data Type

As the function is parsed using the compiler, the output type cannot be guessed by the module, hence it needs to be set by the user to the correct data type.

Top

GetFieldData

MapDataFieldFromNodeToElem

MapFieldDataFromElemToNode

MapFieldDataFromSourceToDestination

MapFieldDataOntoElements

MapFieldDataOntoNodes

RegisterWithCorrespondances

SetFieldData

SetFieldDataToConstantValue

SwapFieldDataWithMatrixEntries

ChangeMesh

AlignMeshBoundingBoxes

ConvertHexVolToTetVol

ConvertMeshToPointCloud

ConvertMeshToUnstructuredMesh

ConvertQuadSurfToTriSurf

EditMeshBoundingBox

FlipSurfaceNormals

ProjectPointsOntoMesh

ReorderNormalCoherently

ResampleRegularMesh

ScaleFieldMeshAndData

SetFieldNodes

TransformMeshWithTransform

Converters

ConvertMatrixToScalar

ConvertMatrixToString

ConvertRealToComplexMatrix

ConvertScalarToMatrix

DataIO

ReadBundle

ReadField

ReadMatrix

WriteField

WriteMatrix

FiniteElements

BuildFEMatrix

BuildFEVolRHS

FlowControl

BooleanCompare

Compare one or two matrices using boolean operators, and send different outputs, or quit SCIRun, depending on the result of the boolean comparison.

Detailed Description

The BooleanCompare module will evaluate one or two input matrices and return different results based ont the evaluation. The module will evaluate either the values, size, or norm of each of the matrices with boolean operations, and can return any one of three inputs, as well as quit SCIRun. The inputs will be compared element by element based on the criteria chosen in the Condition option and perform the actions chosen in the Then option if true and Else option if false. Module also send the result of the comparison as the seond output matrix.

Inputs

MatrixA - (Required) First matrix for comparison.
MatrixB - (Optional) Second matrix for comparison. If this port is not used, most of the comparsion options will not be possible.
PossibleOutput - (Optional) Possible matrix to send as an output to the module.

Outputs

OutputMatrix - The output matrix of the module. This will be identical to one of the three inputs of the module, or will be null depending on the inputs and options of the module.
BooleanResult - Matrix of 1x1 containing either 1 or 0 indicating the result of the boolean comparison performed by the module.

Options

Any combination of the values (default), size, and norm (except a size and norm) of the first two input matrices can be compared as long as the resulting size of the objects are the same. The size of one matrix can be compared to the values of the other matrix if it has two entries. Likewise, the norm of one matrix can only be compared to the value of another matrix if it is 1x1.

The condition option sets the method of comparing the input matrices. If the operator is true, then the module will result in the action chosen in the Then_Option menu, and if false it will perform the action selected in the Else_Option menu. Operator options are:

‘A is non-zero’ - (default) true if there are any non-zero entries of A .
‘A and B are non-zero (and)’ - true if any corresponding entries of A and B are both non-zero.
‘Either A or B is non-zero (or)’ - ture if either A or B has non-zero entries
‘A is greater than or equal to B (>=)’ - true if entries of A are greater than or equal to B’s.’
‘A is greater than B (>)’ - true if entries of A are greater than B’s.
‘A is equal to B (==)’ - true if all the entries of A are the same as B.
‘A is less than B (<)’ - true if entries of A are less than B’s.
‘A is less than or equal to B (<=)’ - true if entries of A are less than or equal to B’s.

There can be ambiguous scenarios with the greater or equal, greater, less, less or equal options in the module if the input matrices have a size of more than one. In these cases, ie, if there are a set of entries which are both less than and greater than, the number of entries and the magnitude of the difference will determine which input is greater or less. Consider comparing the matrix norms to avoid ambiguity of the results. If there is no second matrix input, the first matrix can only be evaluated by non-zero entries (or size or norm) of the matrix.

The results options establishes the output of the module based on the result of the comparison. If the condition returns true, the action indicated in the Then option will be performed, If false, the Else option will be performed. Possible actions are:

‘Return First Input’ - (Then default) returns the first matrix input.
‘Return Second Input’ - returns the second matrix input.
‘Return Third Input’ - returns the third matrix input.
‘Return null’ - (Else default) returns an emplty matrix handle.
‘Quit SCIRun’ - Quit the current instance of SCIRun.

If the second or third inputs are selected for output and no matrix is input into these ports, the module will return null.

Top

ChooseInput

Inverse

SolveInverseProblemWithTikhonov

SolveInverseProblemWithTikhonov solves the inverse problem as a (weighted) minimum norm problem by applying a Tikhonov L2-norm regularization. It solves the minimization problem: $\hat{x}=argmin_x \|Ax -Ly\|^{2}_{2} + \lambda\|Rx\|^{2}_{2}$

Detailed Description

The module has four inputs, three outputs, and a graphical user interface (UI) where the regularization parameter can be chosen or computed. All inputs can be generated by SCIRun, or created elsewhere or loaded from Matlab files or the Matlab interface.

Input

Forward problem matrix, $A$ : This matrix describes the relationship between solution and measured signals $A x = y$ .

For example, this matrix can be computed by solving the forward problem e.g. using finite or boundary element methods (see modules in BioPSE Forward, FiniteElements category).

Solution constraint matrix, $R$ : This matrix is used to constrain the solution. It imposes some a priori knowledge upon the minimization problem to select solutions with specific properties (expressed as a solution covariance e.g. to achieve maximally smooth solutions). If no input is given the identity matrix will be used.
Data vector, $y$ : These are the measurement data which have to be provided as matrix which should only contain one column.
In case of having a time series (multiple columns), it is recommended to use the module SelectSubmatrix to iterate over the different time instances (columns). In more detail, for each time instance, SelectSubmatrix would provide the data of the current time instance for SolveInverseProblemWithTikhonov to perform an estimation of the inverse solution.
Residual constraint matrix, $L$ : This matrix is used to weight the measurements (e.g. by an inverse covariance matrix of the measurement channels). If no input is given, the identity matrix will be used.

IMPORTANT: Both, residual constraint as well as the solution constraint matrix can be used in single matrix form (such as $L$ and $R$ ) in the minimization problem or as a squared matrix version (such as $L^T L$ and $R^T R$ ) respectively. This option must be properly selected by the user in the UI:

alt text

Output

Inverse solution, $\hat{x}$ : computed solution estimate.
Regularization parameter, $\lambda$ : used regularization parameter.
Regularized inverse matrix, $G$ : linear inverse operator that gives a solution estimate equation $\hat{x} = G y$ . It actual value depends on the selected formulation (underdetermined or overdetermined) and requires the inversion of a matrix. It is only calculated if this port is connected to another module’s input port. The user can select between the formulations using the module GUI (see section Computation).

underdetermined:

$G=RR^TA^T (ARR^TA^T + \lambda LL^T)^{-1}$

overdetermined:

$G=(A^TL^TLA + \lambda R^TR)^{-1}A^TL^TL$

Computation

The algorithm has two different ways of computing the solution: the underdetermined and the overdetermined formulations. To choose which one will be solved the module has three options:

Automatic selection. The algorithm will select underdetermined or overdetermined based on the dimensions of the Forward matrix.
Manual selection of the undetermined formulation.
Manual selection of the overdetermined formulation.

These options are presented in the GUI as follows:

alt text

Both cases use Gaussian elimination to calculate the unknown $\hat{x}$ , but they differ in the equations to solve for:

underdetermined:

$(A R R^T A^T + \lambda L L^T) b = y, \hat{x} = R R^T A^T b$

overdetermined:

$(A^T L^T L A + \lambda R^T R) \hat{x} = A^T L^T L y$

However, If the output port of the inverse operator is connected to another module’s input the inverse operator $G$ is used to compute the solution estimate $\hat{x}$ such as $\hat{x} = G y$ .

In both cases the used regularization parameter can be chosen in the UI. The available options are:

Fix $\lambda$ manually.

alt text

Automatic selection of $\lambda$ : the corner of the L-curve is determined by maximal curvature. A number of regularization parameter points (different $\lambda$ values) can be specified in the L-curve plot which are than equally distributed over the range (“Lambda Range”, see below) of $\lambda$ ’s to be used in the L-curve computation.
Fix $\lambda$ manually based on the range of regularization parameters ( $\lambda$ ) specified by the “Lambda Range” input.

alt text

For the options that use the L-curve, the user can define the range and step size in the UI:

alt text

Top

Math

AddKnownsToLinearSystem

This module deals with solving a linear system A*u=b when some values of the vector u is already known. The module will modify the linear system according to the known values.

Detailed Description

This module takes 3 inputs:

LHS Matrix is an NxN Matrix (must be a SparseRowMatrix).
RHS Vector is the right hand side vector, an Nx1 Matrix.
X Vector is an Nx1 Matrix specifying the known variables in the linear system LHS. If the kth variable is known, x(k) is its value, otherwise x(k) should be set NaN.

This module returns 2 outputs:

OutPutLHSMatrix is an NxN Matrix.
OutPutRHSVector is an Nx1 Matrix.

The solution:

inv(A2)*b2

has the same value as x at the non-NaN positions.

Top

AddLinkedNodesToLinearSystem

AddLinkedNodesToLinearSystem will link nodes in a finite element mesh and solve them as a single value.

Detailed Description

AddLinkedNodesToLinearSystem works with AddKnownsToLinearSystem and SolveLinearSystem to force nodes in a finite element mesh to solve to the same value. This module is useful in solving for regions with homogeneous field properties, such as with a perfect conductor in an electric field. The algorithm to do this involves combining rows in the stiffness matrix corresponding to the nodes to solve together. The module also creates a mapping Matrix that will map the results of the solved linear system to the original mesh.

Input Ports

This module takes 3 inputs. The first two are the NxN Matrix (LHS) and the right hand vector (RHS), which is a Nx1 Matrix, for a linear system (Ax=b) and correspond to the two outputs of the AddKnownsToLinearSystem module.

The third input is a matrix (LinkedNodes) representing the data marking the nodes to link on the same mesh used in the BuildFEMatrix module. The nodes should be marked with an integer value so that nodes to be linked will have the same value. Any number of linked node sets can be used by using a different value, i.e., independent sets of nodes to be linked must be marked 1,2,3 creating three regions of linked nodes. The remaining nodes should be marked NaN. This can be accomplished be using MapFieldDataOntoNodes and using the Default Outside Value of NaN option and a Maximum Distance of some value that is small relative to your mesh size. Then use GetFieldData to port the matrix into this module.

Output Ports

This module returns 3 outputs. The first two are the reduced Matrix (OutputLHS) and right hand vector (OutputRHS), which is a Nx1 Matrix, for a linear system to use in SolveLinearSystem . The third is a mapping Matrix (Mapping) to restore the data (solution vector from linear system solution) to the proper size. To do this, multiply the mapping matrix and the first output of SolveLinearSystem . The resulting vector can then be applied to the original mesh used in the calculation.

Top

AppendMatrix

BuildNoiseColumnMatrix

CollectMatrices

ComputePCA

ComputeSVD

ConvertMatrixType

CreateComplexMatrix

CreateGeometricTransform

This module builds a 4x4 geometric transformation matrix capable of translation, scaling, rotation, sheering and permutation.

Detailed Description

Default

The default transformation matrix offers no translation, scaling, rotation, shear, or permutation. The output under default settings is a 4x4 identity matrix. By default the module also only applies a single transformation option. For example, if the translate feature is applied the result will only translate, once the user switches to another option (say rotation) the output transformation matrix will return to the original identity matrix and only apply rotation. In order to apply multiple transformations, the user must first click the “composite transform” button so that the transformation remains. Once this button is pushed, the output transformation now becomes the default matrix.

Input Port

The module accepts a 4x4 matrix as an input transformation matrix and populates the output to reflect the input matrix. If a matrix of any other size is used as an input, no error is thrown but the matrix is not recognized - resulting in the same, default 4x4 identity matrix.

UI Features:

Each UI feature is selectable via radio button.

Translate

Translate allows the user to define the x, y, and z directions for translation via UI sliders.

Scale

Scaling is manipulated by logarithmic sliders at the bottom of the page. A Log Calculator (base 10) is provided at the bottom of the window for convenience.

Above the scale sliders, translation options are also given as X, Y, and Z, sliders; however, the translational shift is also determined by the log scale factor of the respective cardinal direction. For example, the x translation is augmented or diminished by the Log ScaleX slider.

Rotate

Rotation allows the user to define the angle (theta) of rotation on the bottom most slider bar. This rotation angle is applied to a portion of the rotation axes (labeled “Rotate Axis X/Y/Z”). For example, if the Rotate Axis Z is set to 1.00 and the Rotate Theta angle is set to 90. The transformation matrix will rotate an object around the Z axis by 90 degrees (centered at the origin - more on this below). If the X and Z axes are equal to each other, the transformation gives equal weight to rotation in the X and Z directions, no matter the magnitude of each slider value.

The origin can be defined by the slider bars above under the heading “Rotation Fixed Point.” If X, Y, and Z are set to 0 in this section, the origin corresponds to the original origin of whatever mesh the module is applied to.

Shear

The shear stress component of the module allows the user to define a shear stress vector in the upper panel of the UI. The vector is defined using X, Y, and Z force components. The lower half of the component has allows the user to define fixed plane components with A, B, and C representing the X, Y, and Z directions. The final component D defines the offset from the origin (in the direction of the stress vector) after the stress is applied.

Permute

The permute feature allows the user to flip axes. With the FlipX/FlipY/FlipZ commands, the signs of the respective axis are reversed. With the Cycle+/Cycle- options, the axes themselves are alternated (ex. x = y, y = z, z = x). This does not actually change the coordinate system of the field that is being translated. It only alters the matrix to flip over the axis lines.

In order to use the widget feature, the visualization output port must be attached to a viewer window. Once attached a small cubic widget appears on the screen. The widget can be scaled using the Uniform Scale slider (but it does not allow for singe directional changes i.e. you cannot scale in only the X direction…all cardinal directions scale together). Two other features appear in the UI: 1 - Resize Separable adds rotation spheres to the widget (more on this below) and 2 - Ignore changes allows the user to place, scale, and adjust the widget as they choose without applying assigning the transformations in the output matrix. A user may use the Ignore feature to adjust the size and shape of the widget to fit their geometry before they actually start manipulating the transformation.

Once the widget is in place, the user can manipulate it in the viewer window. By holding the shift key and clicking on a portion of the widget, the user can “grab” the widget and move it. Caps Lock also works to capture the widget. If the Resize Separately box is checked in the UI, spheres appear at the center of each of the 6 faces of the cube. Additionally, the user can turn on these spheres by clicking on the widget while holding down the shift+opt key on a mac (EDIT REQUIRED TO ACCOUNT FOR WINDOWS AND LINUX CONTROLS).By so clicking, the user cycles through all of the widget options (turning them on and off with each click). Shift+clicking each part of the widget allows for the following transformations:

Gray Widget Border:

–Translation

Blue Sphere:

–Rotation

Green Cylinders:

Scaling (if the widget has not been rotated while Ignore Changes was applied)
Shearing (if the user has rotated the widget with the Ignore Changes applied).

Top

CreateMatrix

CreateStandardMatrix

EvaluateLinearAlgebraBinary

This module performs one of a number of selectable matrix operations using the two input matrices.

Detailed Description

One of a number of binary matrix operations can be selected from the GUI and is then applied to the two input matrices to produce a new matrix that is then sent to the output port. The operations are X, +, Normalize, Select Rows, Select Columns, or Function.

“A X B” does a matrix multiply of the two matrices. The number of rows in the first matrix must match the number of columns in the second matrix. The output matrix has the same number of columns as the first matrix and the same number of rows as the second.

“A + B” performs a matrix addition. The two input matrices must be the same size. The elements are added in a piecewise fashion. This is equivalent to selecting “Function” and using ‘x+y’ as the function description

“Normalize A to B” computes the min and max values of the second matrix, and then linearly transforms all of the elements in the first matrix so that they fall within the range of those min and max values.

“Select Rows” uses the values in the B input matrix as row indices to extract from the A input matrix. The B input matrix must be a Column Matrix containing valid row index values into the A matrix. For example, if the B matrix contains [3 5] and the A matrix is 100x200, then the resulting matrix will be 2x200 and contain rows 3 and 5 from the A matrix.

“Select Columns” uses the values in the B input matrix as column indices to extract from the A input matrix. The B input matrix must be a ColumnMatrix containing the valid column index values into the A matrix. For example, if the B matrix contained [3 5] and the A matrix is 100x200, then the resulting matrix will be 100x2 and contain columns 3 and 5 from the A matrix.

“Function” allows an arbitrary function of two variables to be evaluated for each number pair in the two input matrices. This requires that the two matrices are the same size. The variable representing the element from the A matrix is ‘x’, and the variable for the element from the B matrix is ‘y’. The function is specified using SCIRun’s simple function parser. There are a number of mathematical functions available for use. They are:

Operators:

+:Add two numbers:

      4+3 = 7

-:Subtract one number from another:

      4-3 = 1

Multiply two numbers:

      4*3 = 12

Divide one number from another:

      12/3 = 4

sin:Sine of a number in radians:

      sin(x)

cos:Cosine of a number in radians:

      cos(x)

sqrt:Square root of a number:

      sqrt(4) = 2

sqr:Square of a number:

      sqr(2) = 4

ln:Natural logarithm of a number:

      ln(x)

exp:e raised to the nth power:

      exp(ln(x)) = x

log:Log base 10 of a number:

      log(100) = 2

abs:Absolute value of a number:

      abs(-3) = 3

pow:One number raised to the power of another:

      pow(3, 2) = 9

random:Return a uniform random number between 0 and 1:

      random()

Top

EvaluateLinearAlgebraUnary

Performs one of a number of selectable unary matrix operations to the input matrix.

Detailed Description

One of a number of unary matrix operations can be selected from the GUI and is then applied either to the whole matrix or to each element in the matrix, depending upon which operation is selected. The operations are Round, Ceil, Floor, Normalize, Transpose, Sort, Subtract Mean, or Function.

Round, Ceil, and Floor are used to convert each element in the input matrix into an integer value.

Normalize linearly transforms each element such that they all end up between 0 and 1.

Transpose constructs a new transpose matrix containing the same elements as the input matrix. For example, if the input matrix was of size 4x20, the output matrix will be of size 20x4.

Sort does an insertion sort on the elements of the input matrix. The elements will be sorted such that the smallest element will be at the top of the matrix and the largest element will be at the end. If the matrix is not a row or column matrix, the matrix is sorted in a row-scanline order. For example, in a 2x30 matrix, the first row would contain the lower half of the values and the second row would contain the upper half.

Subract Mean computes the mean value of the matrix, and then subtracts that value from each element in the matrix.

Function allows an arbitrary function to be evaluated for each element in the matrix. The current value is represented as the variable ‘x’. For instance, the default ‘x+10’ function adds 10 to each element in the matrix. A function of just ‘10’ would set each element in the matrix to be 10. The function is specified using SCIRun’s simple function parser.

There are a number of mathematical functions available for use:

Operators

+:Add two numbers:

      4+3 = 7

-:Subtract one number from another:

      4-3 = 1

Multiply two numbers:

      4*3 = 12

Divide one number from another:

      12/3 = 4

sin:Sine of a number in radians:

      sin(x)

cos:Cosine of a number in radians:

      cos(x)

sqrt:Square root of a number:

      sqrt(4) = 2

sqr:Square of a number:

      sqr(2) = 4

ln:Natural logarithm of a number:

      ln(x)

exp:e raised to the nth power:

      exp(ln(x)) = x

log:Log base 10 of a number:

      log(100) = 2

abs:Absolute value of a number:

      abs(-3) = 3

pow:One number raised to the power of another:

      pow(3, 2) = 9

random:Return a uniform random number between 0 and 1:

      random()

Top

ReportColumnMatrixMisfit

ReportComplexMatrixInfo

ReportMatrixInfo

SelectSubmatrix

SetSubmatrix

Redefines a specified region of an input matrix to new, user-defined values.

Detailed Description

This module will replace existing values within a matrix with new values defined by the user. The module has 3 input ports. The first input port reads in the matrix the user wishes to change. The second port reads in the values that the user wishes to place inside the existing matrix. The third port is optional and reads in a 2x1 or 1x2 matrix that defines at which row and column the replacement will begin. The first number in the third port input matrix defines the initiating row. The second defines the column. If the third port is left empty the module defaults to row 0 / column 0, but these values can be altered manually within the UI.

Example 1:

Input port 1 =

       [1 9 -13; 20 5 -6]

Input port 2 =

       [a b]

Input port 3 =

       [1 1]

Output =

       [1 9 -13; 20 a b]

Example 2:

Input port 1 =

       [1 9 -13; 20 5 -6]

Input port 2 =

       [a; b]

Input port 3 =

       [0 1]

Output =

       [1 a -13; 20 b -6]

Note: The size of the input matrix cannot be altered by the size and starting points of the replacement and position matrices. In other words, if the resulting matrix would have larger dimensions than the original input matrix, the module with throw and error.

Top

SolveLinearSystem

The SolveLinearSystem module is used to solve the linear system $Ax=b$ , where the coefficient matrix $A$ may be dense or sparse, $b$ is a given right-hand-side vector, and the user wants to find the solution vector $x$ .

Detailed Description

The SolveLinearSystem module takes two input matrices and returns three matrices. The first input port takes the coefficient matrix $A$ , which may be a dense $n \times n$ matrix or a sparse $n \times n$ matrix. The second input port takes the right hand side vector $b$ as an $n \times 1$ dense matrix. Here, the module is assuming that an $n \times n$ system is being solved.

The first of the three output ports returns the solution vector $x$ as an $n \times 1$ dense matrix. The second output port returns the number of iterations required to reach convergence as a $1 \times 1$ dense matrix and the third output port returns the norm of the residual vector, again as a $1 \times 1$ dense matrix.

The GUI for this module is used to define the solution method for the module and monitor the convergence towards the solution.

alt text

Methods Tab

alt text

The Methods tab allows the user to select one of four solution algorithms for numerically solving sparse systems of linear equations:

Conjugate gradient
Biconjugate gradient
Jacobi
MINRES

Each solution method comes with the option of choosing a preconditioner for the numerical solution algorithm, which is set with the Preconditioners tab:

alt text

At present, only the Jacobi preconditioner is available. However, there is the option of using no preconditioning.

Convergence Criteria

The next section of the GUI sets up the convergence criteria for the numerical solution.

alt text

To achieve convergence of the numerical solution, the norm of the residual must be less than the target error as given in the slider. The next slider sets the maximum number of iterations that are allowed to achieve solution. This can take a value anywhere between 0 and 20000.

The module has the ability to write solutions at regular intervals and this flag is set by clicking on the Emit partial solutions check-box. The frequency of writing the solutions is set with the next slider.

Finally, the option Use the previous solution as initial guess, which is set by clicking the check-box, allows the user to either continue a simulation run looking for better convergence, or run a second simulation for which it is expected that the second solution may be close to the first.

A useful strategy for solving simulation problems is to begin with a small number of iterations to check that the solution will converge and then use the Use the previous solution as initial guess option to continue the simulation. Alternatively, to stop a diverging, or at least non-converging, simulation the Target error can be dynamically changed to a residual error level already obtained by the solver.

Iteration Progress

The bottom section of the GUI shows how the solution is progressing.

There is an iteration counter to show how many iterations have been completed, the value of the original error (this will be 1.0 unless the Use the previous solution as initial guess option has been used) and thevalue of the current error. These quantities are summarised graphically in the convergence plot.

Further reading: [http://www-users.cs.umn.edu/~saad/books.html Y. Saad, Iterative methods for sparse linear systems, second edition (2000)].

Top

SolveMinNormLeastSqSystem

This module computes the minimal norm, least squared solution to a Nx3 linear system.

Detailed Description

Given four input ColumnMatrices (v0,v1,v2,b), it finds the three coefficients (w0,w1,w2) that minimize:

       | (w0v0 + w1v1 + w2v2) - b |

If more than one minimum exists (the system is under-determined), the coefficients such that (w0,w1,w2) has a minimum norm is selected.

The outputs are a vector (w0,w1,w2) as a row-matrix and the ColumnMatrix (called x), which is:

       [ w0v0 + w1v1 + w2v2 ]

Top

MiscField

BuildMappingMatrix

BuildMatrixOfSurfaceNormals

CalculateMeshCenter

GetMeshQualityField

Calculates mesh quality based on several generally accepted algorithms. Default: Scaled Jacobian

Detailed Description

Mesh quality reporting options: Jacobian/Scaled Jacobian – Jacobian and Scaled Jacobian are based on accepted mesh quality metrics as calculated by the Verdict software library. In brief, for a single node, the Jacobian matrix is defined as:

                        | x_1 - x_0     x_2 - x_0     x_3 - x_0 |
 A_0 =                  | y_1 - y_0     y_2 - y_0     y_3 - y_0 |
                        | z_1 - z_0     z_2 - z_0     z_3 - z_0 |

The minimal determinant of these matrices for each node of an element is known as the ‘Jacobian’ of the element. (Callahan et al. 2009)

Volume – Returns the volume of each element.

Scaled Inscribed/Circumscribed Ratio – Mesh quality is determined by the ratio between the radii of the largest possible inscribed sphere compared to the smallest possible circumscribed sphere of each tetrahedral element. The radius is normalized against he ratio of an equilateral tetrahedron 1:3.

Top

ReportFieldGeometryMeasures

ReportFieldInfo

NewField

CalculateNodeLocationFrequency

ClipFieldByFunction

ClipFieldByMesh

ClipVolumeByIsovalue

ConvertMatricesToMesh

CreateImage

CreateLatVol

ExtractSimpleIsosurface

This moudle extracts an isopotential surface from a scalar field.

Detailed Description

The ExtractIsosurface module is used to extract one or more isopotential surfaces from a scalar field using the Marching Cubes algorithm. The isopotential surfaces are surfaces for which the scalar value would interpolate to a constant isovalue. The module can output a SCIRun field and geometry (for faster module execution, if only one is needed, deselect the output type that is not needed). The isovalues can be specified in several ways.

Slider

The Slider tab allows the user to select one isovalue using a slider bar or to type in one isovalue manually. The slider bar ranges from the minimum and maximum values of the input field. This can be used with great effect to interactively move the isosurface around when the Update Auto option is specified. Other update options are On Release, which updates the isosurface when the slider button is released, and Manual, which updates the isosurface when the module is executed.

Quantity

The Quantity tab allows for the selection of several regularly spaced isosurfaces (the list of isovalues is not editable). This is particularly useful for isocontouring as it gives a contour-map effect for where the isosurfaces would be located.

List

The List tab allows the user to type in an arbitrary spaced delimited list of isovalues to be used. In addition to hard numbers, percentages relative to the field minimum and maximum may be specified as well. For instance, 50% would specify the isovalue in the center of the min-max range, whereas 50.0 would isosurface at a value of 50.0.

Matrix

Isovalues can be passed into the field in the Optional Isovalues port, which expects a Nx1 matrix. The Matrix tab must be selected and the module executed to populate the list of isovalues from the Optional Isovalues input matrix. A surface will be created for each value in that matrix. The ExtractIsosurface-probe.srn example network demonstrates this using the GenerateSinglePointProbeFromField and SwapFieldDataWithMatrixEntries modules to interactively select the isosurface with a probe using this port.

The Build Output Field option determines whether or not a surface field is created. The Build Output Geometry option determines whether or not geometry data is created. Transparency can be enabled for geometry output by selecting the Enable Transparency option. If there is no ColorMap present then the default color is used for the output geometry.

This module can work on scalar fields with the following mesh type: LatVol, StructHexVol, HexVol, TetVol, Prism, Image, StructQuadSurf, QuadSurf, TriSurf, Scanline, StructCurve, and Curve. Isosurfaces are generated for volume meshes, isocontours are generated for surface meshes, and isopoints are generated for edge meshes.

If the scalar fields contain cell-centered data, the surfaces are created along the appropriate cell faces. In the case where the isovalue exactly equals the scalar data only the face between the cell and its neighbor with a great scalar value will be extracted.

Output

There are four output ports:

The first output port contains the field
The second output port is the geometry (useful for large data sets if the extracted surface will only be viewed)
The third output port contains a mapping matrix to the nodes used to build the isosurface
The fourth output port contains a mapping matrix to the cells used to build the isosurface.

Top

FairMesh

GeneratePointSamplesFromField

GeneratePointSamplesFromFieldOrWidget

GenerateSinglePointProbeFromField

GetCentroidsFromMesh

GetDomainBoundary

GetFieldBoundary

GetSliceFromStructuredFieldByIndices

InterfaceWithCleaver

InterfaceWithTetgen

This module is a port to open and run Tetgen, a delauney tetrahedralization software package, within SCIRun.

Detailed Description

InterfaceWithTetgen is a module that will make a tetrahedral mesh from a trisurf mesh or a point cloud. This is the easiest way to turn a surface mesh into a volume in SCIRun. Using delauney tetrahedralization, tetgen will find the tetrahedral mesh that will connect the input points with the highest quality elements, i.e., the element face area are as equal as possible. For more information about tetgen an its capabilities, please refer to the Tetgen website.

In order for tetgen to run effectively, the flags must be properly set. If using a surface input, the mesh must be a valid trisurf mesh that is completely inclose and without overlapping/crossing elements. If using only a point cloud input, the first option (Tetrahedralize a piecewise linear complex (PLC)) must be disabled. In the case of a point cloud only input, the output will be a convex hull of the points. If this module is taking too long (several minutes) and you are not sure why, try getting rid of any quality or size constraints (should finish quickly, as fast as a few seconds depending on the mesh) and then gradually reintroducing them. The few the options enabled, the faster and more likely to solve the tetrahedralization.

There are four inputs:

Main (Required): The main field to be processed by tetgen. The outer surface or Tetrahedral volume field to refine.
Points (Optional): If there is a PointCloud attached to this input, the point in it will be included in the output tetvol. Data on this field is meaningless.
Region Attribs (Optional): If a PointCloud is attached the points will be considered points inside the different regions. The data will be used as the volume constraint for that region. For the volume constraint to be respected you must pass the ‘a’ command line switch.
Regions (optional): This is a dynamic input, each input should be a surface field, that defines a region inside the Main Input.

The module outputs a tetrahedral mesh.

Top

JoinFields

SplitFieldByConnectedRegion

SplitFieldByDomain

Python

InterfaceWithPython

PythonObjectForwarder

Render

ViewScene

This module displays interactive graphical output to the computer screen. Use the ViewScene to see a geometry, or spatial data. The ViewScene provides access to many simulation parameters and controls, thus, indirectly initiates new iterations of the simulation steps important to computational steering.

Detailed Description

Autoview restores the display back to a default condition. This is very useful when objects disappear from the view window due to a combination of settings.

Set Home View captures the setting of the current view so you can return to it later by clicking the Go home button. Go home restores the current home view.

Views lists a number of standard viewing angles and orientations. The view directions align with the Cartesian axes of the objects. The Up vector choice sets the orientation of the objects when viewed along the selected axis.

From the ViewScene window, the left corner of the control panel contains performance indicators that document the current rendering speed for the display. More advanced graphics performance results in a higher drawing rate.

The Viewer can be cloned with the NewWindow button in the menu. When a new window is created it is locked to the original window, meaning that rotations in one are copied to the other window. This mode is called the ‘View Locking Mode’ and is indicated with a little ‘L’ in the lower right corner. To independently rotate the viewers, release the lock by pressing ‘L’ in the window that needs to be unlocked. If one presses ‘L’ again the window will return to locking mode in which all the mouse movements are copied to all other windows that have locking mode switched on.

To improve navigation in 3D data and help facilitate the placement of widgets, it is suggested to use multiple windows that view the object from different angles. By pressing 1-8 in the window one can quickly move through different views, that look at the object from different angles.

A small plus sign (+) appears in the lower right corner of the ViewScene window. Clicking on the plus sign reveals the extended control panel.

The ViewScene module also supports a series of hotkeys:

1-8: Standard views that align with the cartesian axis.
CTRL 1-9: Import view from Viewer Window 1-9.
0: Restore display back to default view (Autoview).
CTRL H: Capture current view and store it (Set Home View).
H: Go to captured view (Go Home).
A: Switch Axes ON/OFF.
B: Switch Bounding box mode ON/OFF.
C: Switch Clipping ON/OFF.
D: Switch Fog ON/OFF.
F: Switch Flat shading ON/OFF.
I: Display latest information on hotkeys.
K: Switch lighting ON/OFF.
L: Switch view locking ON/OFF.
O: Switch orientation icon ON/OFF.
P: Switch orthographic projection ON/OFF.
U: Switch backculling ON/OFF.
W: Switch wireframe ON/OFF.

Top

String

CreateString

GetNetworkFilename

JoinStrings

NetworkNotes

PrintDatatype

PrintMatrixIntoString

PrintStringIntoString

ReportStringInfo

SplitFileName

Visualization

CreateStandardColorMap

GenerateStreamLines

This module visualizes vector fields by generating curves that interpolate the vector of vectors in a Field.

Detailed Description

The Vector Field input port is the vector field on which the path intergration of the seed points will be performed. This may be a vector field with any volume geometry type. Surfaces and lower order fields do not currently work due to numerical error.

The second input port, Seeds, contains the initial values for which the vector will be computed. This may be a field of any type, as just the node positions are used. Seeds which are not contained within the vector field are just discarded. The module requires use of both field inputs in order to execute.

The GenerateStreamLines module has one output, Streamlines, a CurveMesh, representing a collection of stream lines computed for the Vector field given the set of initial seed points.

This module uses one of several similar numeric integration methods. They are taken directly from Numerical Analysis by David Kincaid and Ward Cheney, c1991. Adams-Bashforth is a Multi-Step method that offers the fastest performance by reusing existing samples when possible. It presents some interesting artifacts on discontinuous models such that it is easy to visualize where those discontinuities take place. Heun is a second order Runge-Kutta solver, and is sufficient for most smoothly varying fields, such as linearly interpolated gradient fields over volume elements. Classic 4th Order Runge-Kutta is presented for reference and provides excellent results in general. Adaptive Runge-Kutta-Fehlberg is a 5/6 order solver which provides the best overall results at the cost of more computation time. It is also the only adaptive method, meaning the step size of the algorithm is adjusted dynamically as the stream moves through the vector field.

All of the computation methods are similar in that they take a step, (based upon the Step Size indicated) examine the derivative at that point, and then procede in that new direction. Adaptive Runge-Kutta-Fehlberg also determines if a stepsize correction is necessary. This determination is based upon the Error Tolerance value.

The GenerateStreamLines GUI includes text fields for Error Tolerance, Step Size, and Maximum Steps. The Error Tolerance text field represents the margin of error when doing an adaptive calculation of the stream lines. Maximum Steps represents the maximum number of iterations.

The user can specify whether streamlines are computed in negative and/or, positive directions by changing the Direction radio buttons. The Color Style options are based on either the seed number, integration step, distance from the seed, or the total distance, which will affect how values are attached to the output field. By selecting seed number, the output field will range from zero to the number of seed points so that every stream line has exactly one value. The integration step option changes the value of output field such that they start at zero where the seed point is at and go up by one for each integration step away in either direction. The distance from seed is similar to the integration step but based on the cord length distance from the seed. Whereas the total length is based on the total cord length from the seed point.

The Filter Colinear Points check box is a postprocess on the streams. It passes over the streams and removes all points that are too close together, as well as points that are colinear. It is useful for rendering the streamlines as it greatly simplifies them while retaining their visual appearance.

Top

RescaleColorMaps

ShowAndEditDipoles

ShowColorMap

ShowField

ShowFieldGlyphs

This module visualizes the data that makes up a Field. When possible and selected, the glyph takes its color from the data values that permeate the field.

Ports

This module has 6 input ports, 3 field inputs and 3 color map inputs. The only required port is the first field input port because that holds the data that is visualized. By default, ports will be set to primary input.

Secondary and Tertiary Ports
The secondary and tertiary ports can be used to scale vector parameters like width. Ex: When rendering vectors as a cone the orientation and length of the cone are determined by the primary field, but the secondary field can be used to change the radius of the cone.

They can also be used to assign colors based on data besides the primary field. Ex: If you want to render scalars in RGB, you can give a secondary input of a vector or tensor and set the coloring to RGB Conversion through the secondary input.

Color

By default, glyphs is displayed using the default color, which is editable from the GUI.

Color Map
If there is a color map and field attached to the selected input port, then the data in the selected field input is used as an index into the corresponding color map, and the glyph is rendered with the color at that point.

Type	Description
Scalar	Uses scalar value as index
Vector	Uses vector’s length as index
Tensor	Uses the vector magnitude of the 3 eigenvalues as the index

RGB Color Conversion
If there is a field attached to the selected input port, then the data in the selected field is converted into a color. The RGB color components are generated by the absolute value of vector x, y, z components:

   (R = |x|, G = |y|, B = |z|)

Type	Description
Scalar	Creates gray-scale mapping
Vector	Normalized vector creates RGB colors
Tensor	Principle eigenvector(normalized) creates RGB colors

Top

SCIRun 5 Modeling - Simulation - Visualization

SCIRun Modules

Input Variables

Output Variable

Available Functions

Input Ports

Output Port

Example Functions

Output Data Type

Input Variables

Output Variable

Available Functions

Input Ports

Output Port

Output Data Type

Input Port

Output Ports

GUI Options

Input

Output

Computation

Input Ports

Output Ports

Default

Input Port

UI Features:

Translate

Scale

Rotate

Shear

Permute

Widget

Operators

Methods Tab

Convergence Criteria

Iteration Progress

Description of Measures:

Field Attributes displayed:

Slider

Quantity

List

Matrix

Output