SurgSim::Physics::Fem3DElementTetrahedron Class Reference

Class for Fem Element 3D based on a tetrahedron volume discretization. More...

`#include <SurgSim/Physics/Fem3DElementTetrahedron.h>`

Inheritance diagram for SurgSim::Physics::Fem3DElementTetrahedron:

## Public Member Functions

| Fem3DElementTetrahedron ()
| Constructor. More...
| Fem3DElementTetrahedron (std::array< size_t, 4 > nodeIds)
| Constructor. More...
| Fem3DElementTetrahedron (std::shared_ptr< FemElementStructs::FemElementParameter > elementData)
| Constructor for FemElement object factory. More...
void | initialize (const SurgSim::Math::OdeState &state) override
| Initialize the FemElement once everything has been set. More...
double | getVolume (const SurgSim::Math::OdeState &state) const override
| Gets the element volume based on the input state (in m-3) More...
SurgSim::Math::Vector | computeCartesianCoordinate (const SurgSim::Math::OdeState &state, const SurgSim::Math::Vector &naturalCoordinate) const override
| Computes a given natural coordinate in cartesian coordinates. More...
SurgSim::Math::Vector | computeNaturalCoordinate (const SurgSim::Math::OdeState &state, const SurgSim::Math::Vector &cartesianCoordinate) const override
| Computes a natural coordinate given a global coordinate. More...
Public Member Functions inherited from SurgSim::Physics::FemElement
| FemElement ()
| Constructor. More...
virtual | ~FemElement ()
| Virtual destructor. More...
size_t | getNumDofPerNode () const
| Gets the number of degree of freedom per node. More...
size_t | getNumNodes () const
| Gets the number of nodes connected by this element. More...
size_t | getNodeId (size_t elementNodeId) const
| Gets the elementNodeId-th node id. More...
const std::vector< size_t > & | getNodeIds () const
| Gets the node ids for this element. More...
void | setYoungModulus (double E)
| Sets the Young modulus (in N.m-2) More...
double | getYoungModulus () const
| Gets the Young modulus (in N.m-2) More...
void | setPoissonRatio (double nu)
| Sets the Poisson ratio (unitless) More...
double | getPoissonRatio () const
| Gets the Poisson ratio (unitless) More...
void | setMassDensity (double rho)
| Sets the mass density (in Kg.m-3) More...
double | getMassDensity () const
| Gets the mass density (in Kg.m-3) More...
double | getMass (const SurgSim::Math::OdeState &state) const
| Gets the element mass based on the input state (in Kg) More...
virtual void | addForce (SurgSim::Math::Vector *F, double scale=1.0) const
| Adds the element force (computed for a given state) to a complete system force vector F (assembly) More...
virtual void | addMass (SurgSim::Math::SparseMatrix *M, double scale=1.0) const
| Adds the element mass matrix M (computed for a given state) to a complete system mass matrix M (assembly) More...
virtual void | addDamping (SurgSim::Math::SparseMatrix *D, double scale=1.0) const
| Adds the element damping matrix D (= -df/dv) (comuted for a given state) to a complete system damping matrix D (assembly) More...
virtual void | addStiffness (SurgSim::Math::SparseMatrix *K, double scale=1.0) const
| Adds the element stiffness matrix K (= -df/dx) (computed for a given state) to a complete system stiffness matrix K (assembly) More...
virtual void | addFMDK (SurgSim::Math::Vector *F, SurgSim::Math::SparseMatrix *M, SurgSim::Math::SparseMatrix *D, SurgSim::Math::SparseMatrix *K) const
| Adds the element force vector, mass, stiffness and damping matrices (computed for a given state) into a complete system data structure F, M, D, K (assembly) More...
virtual void | addMatVec (double alphaM, double alphaD, double alphaK, const SurgSim::Math::Vector &x, SurgSim::Math::Vector *F) const
| Adds the element matrix-vector contribution F += (alphaM.M + alphaD.D + alphaK.K).x (computed for a given state) into a complete system data structure F (assembly) More...
bool | isValidCoordinate (const SurgSim::Math::Vector &naturalCoordinate) const
| Determines whether a given natural coordinate is valid. More...
template<typename DerivedSub , typename T , int Opt, typename Index >
void | assembleMatrixBlocks (const DerivedSub &subMatrix, const std::vector< size_t > blockIds, size_t blockSize, Eigen::SparseMatrix< T, Opt, Index > *matrix, bool initialize=true) const
| Helper method to add a sub-matrix made of squared-blocks into a matrix, for the sake of clarity. More...
void | updateFMDK (const Math::OdeState &state, int options)
| Update the FemElement based on the given state. More...

## Protected Member Functions

void | initializeMembers ()
| Initializes variables needed before Initialize() is called. More...
void | doUpdateFMDK (const Math::OdeState &state, int options) override
| Update the FemElement based on the given state. More...
void | computeShapeFunctions (const SurgSim::Math::OdeState &state, double *volume, std::array< double, 4 > *ai, std::array< double, 4 > *bi, std::array< double, 4 > *ci, std::array< double, 4 > *di) const
| Computes the tetrahedron shape functions. More...
void | computeStiffness (const SurgSim::Math::OdeState &state, SurgSim::Math::Matrix *k)
| Computes the tetrahedron stiffness matrix. More...
void | computeMass (const SurgSim::Math::OdeState &state, SurgSim::Math::Matrix *m)
| Computes the tetrahedron mass matrix. More...
Protected Member Functions inherited from SurgSim::Physics::FemElement
void | setNumDofPerNode (size_t numDofPerNode)
| Sets the number of degrees of freedom per node. More...
void | initializeFMDK ()
| Initialize f, M, D, K variables. More...
virtual void | doInitializeFMDK ()
| Function to be overridden by the derived classes to initialize the f, M, D, K variables. More...

## Protected Attributes

double | m_restVolume
| Shape functions: Tetrahedron rest volume. More...
std::array< double, 4 > | m_ai
| Shape functions coefficients Ni(x,y,z) = 1/6V ( ai + x.bi + y.ci + z.di ) More...
std::array< double, 4 > | m_bi
std::array< double, 4 > | m_ci
std::array< double, 4 > | m_di
Eigen::Matrix< double, 12, 1 > | m_x0
| The tetrahedon rest state. More...
Eigen::Matrix< double, 6, 6 > | m_Em
| Elasticity material matrix (contains the elastic properties of the material) More...
Eigen::Matrix< double, 6, 12 > | m_strain
| Strain matrix. More...
Eigen::Matrix< double, 6, 12 > | m_stress
| Stress matrix. More...
Protected Attributes inherited from SurgSim::Physics::FemElement
size_t | m_numDofPerNode
| Number of degree of freedom per node for this element. More...
std::vector< size_t > | m_nodeIds
| Node ids connected by this element. More...
double | m_rho
| Mass density (in Kg.m-3) More...
double | m_E
| Young modulus (in N.m-2) More...
double | m_nu
| Poisson ratio (unitless) More...
SurgSim::Math::Vector | m_f
| The force vector. More...
SurgSim::Math::Matrix | m_M
| The mass matrix. More...
SurgSim::Math::Matrix | m_D
| The damping matrix. More...
bool | m_useDamping
| Flag to specify of the damping is used. More...
SurgSim::Math::Matrix | m_K
| The stiffness matrix. More...

## Additional Inherited Members

Public Types inherited from SurgSim::Physics::FemElement
typedef SurgSim::Framework::ObjectFactory1< FemElement, std::shared_ptr< FemElementStructs::FemElementParameter > > | FactoryType
Static Public Member Functions inherited from SurgSim::Physics::FemElement
static FactoryType & | getFactory ()

## Detailed Description

Class for Fem Element 3D based on a tetrahedron volume discretization.

Note
  The inertia property (mass) of the tetrahedron is derived from
  "Theory of Matrix Structural Analysis" from J.S. Przemieniecki
  The force and stiffness matrix of the tetrahedron is derived from
  http://www.colorado.edu/engineering/CAS/courses.d/AFEM.d/AFEM.Ch09.d/AFEM.Ch09.pdf
  The deformation is based on the linear elasticity theory and not on the visco-elasticity theory.
  Therefore the element does not have any damping component.
  Fem3DElementTetrahedron uses linear elasticity (not visco-elasticity), so it does not give any damping.

## Constructor & Destructor Documentation

## Fem3DElementTetrahedron() [1/3]

SurgSim::Physics::Fem3DElementTetrahedron::Fem3DElementTetrahedron | ( |  | ) |

Constructor.

## Fem3DElementTetrahedron() [2/3]

SurgSim::Physics::Fem3DElementTetrahedron::Fem3DElementTetrahedron | ( | std::array< size_t, 4 > | nodeIds | ) |

explicit

Constructor.

Parameters

  nodeIds | An array of 4 node ids defining this tetrahedron element in a overall mesh

Note
  It is required that the triangle ABC is CCW looking from D (i.e. dot(cross(AB, AC), AD) > 0)
  This is required from the signed volume calculation method getVolume()
  A warning will be logged when the initialize function is called if this condition is not met, but the
  simulation will keep running. Behavior will be undefined because of possible negative volume terms.

## Fem3DElementTetrahedron() [3/3]

SurgSim::Physics::Fem3DElementTetrahedron::Fem3DElementTetrahedron | ( | std::shared_ptr< FemElementStructs::FemElementParameter > | elementData | ) |

explicit

Constructor for FemElement object factory.

Parameters

  elementData | A FemElement3D struct defining this tetrahedron element in a overall mesh

Note
  It is required that the triangle ABC is CCW looking from D (i.e. dot(cross(AB, AC), AD) > 0)
  This is required from the signed volume calculation method getVolume()
  A warning will be logged when the initialize function is called if this condition is not met, but the
  simulation will keep running. Behavior will be undefined because of possible negative volume terms.

Exceptions

  SurgSim::Framework::AssertionFailure | if nodeIds has a size different than 4

## Member Function Documentation

## computeCartesianCoordinate()

SurgSim::Math::Vector SurgSim::Physics::Fem3DElementTetrahedron::computeCartesianCoordinate | ( | const SurgSim::Math::OdeState & | state,
|  | const SurgSim::Math::Vector & | naturalCoordinate
| ) |  | const

override virtual

Computes a given natural coordinate in cartesian coordinates.

Parameters

  state | The state at which to transform coordinates
  naturalCoordinate | The coordinates to transform

Returns
  The resultant cartesian coordinates

Implements SurgSim::Physics::FemElement.

## computeMass()

void SurgSim::Physics::Fem3DElementTetrahedron::computeMass | ( | const SurgSim::Math::OdeState & | state,
|  | SurgSim::Math::Matrix * | m
| ) |  |

protected

Computes the tetrahedron mass matrix.

Parameters

  | state | The state to compute the mass matrix from
  [out] | m | The mass matrix to store the result into

## computeNaturalCoordinate()

SurgSim::Math::Vector SurgSim::Physics::Fem3DElementTetrahedron::computeNaturalCoordinate | ( | const SurgSim::Math::OdeState & | state,
|  | const SurgSim::Math::Vector & | cartesianCoordinate
| ) |  | const

override virtual

Computes a natural coordinate given a global coordinate.

Parameters

  state | The state at which to transform coordinates
  cartesianCoordinate | The coordinates to transform

Returns
  The resultant natural coordinates

Implements SurgSim::Physics::FemElement.

## computeShapeFunctions()

void SurgSim::Physics::Fem3DElementTetrahedron::computeShapeFunctions | ( | const SurgSim::Math::OdeState & | state,
|  | double * | volume,
|  | std::array< double, 4 > * | ai,
|  | std::array< double, 4 > * | bi,
|  | std::array< double, 4 > * | ci,
|  | std::array< double, 4 > * | di
| ) |  | const

protected

Computes the tetrahedron shape functions.

Parameters

  | state | The deformable rest state to compute the shape function from
  [out] | volume | the volume calculated with the given state
  [out] | ai | from the shape function, Ni(x, y, z) = 1/6*volume (ai + bi.x + ci.y + di.z)
  [out] | bi | from the shape function, Ni(x, y, z) = 1/6*volume (ai + bi.x + ci.y + di.z)
  [out] | ci | from the shape function, Ni(x, y, z) = 1/6*volume (ai + bi.x + ci.y + di.z)
  [out] | di | from the shape function, Ni(x, y, z) = 1/6*volume (ai + bi.x + ci.y + di.z)

## computeStiffness()

void SurgSim::Physics::Fem3DElementTetrahedron::computeStiffness | ( | const SurgSim::Math::OdeState & | state,
|  | SurgSim::Math::Matrix * | k
| ) |  |

protected

Computes the tetrahedron stiffness matrix.

Parameters

  | state | The state to compute the stiffness matrix from
  [out] | k | The stiffness matrix to store the result into

## doUpdateFMDK()

void SurgSim::Physics::Fem3DElementTetrahedron::doUpdateFMDK | ( | const Math::OdeState & | state,
|  | int | options
| ) |  |

override protected virtual

Update the FemElement based on the given state.

Parameters

  state | \((x, v)\) the current position and velocity to evaluate the various terms with
  options | Flag to specify which of the F, M, D, K needs to be updated

Implements SurgSim::Physics::FemElement.

## getVolume()

double SurgSim::Physics::Fem3DElementTetrahedron::getVolume | ( | const SurgSim::Math::OdeState & | state | ) | const

override virtual

Gets the element volume based on the input state (in m-3)

Parameters

  state | The state to compute the volume with

Returns
  The volume of this element (in m-3)

Computes the tetrahedron volume 1/6 * | 1 p0x p0y p0z | | 1 p1x p1y p1z | | 1 p2x p2y p2z | | 1 p3x p3y p3z |

Implements SurgSim::Physics::FemElement.

## initialize()

void SurgSim::Physics::Fem3DElementTetrahedron::initialize | ( | const SurgSim::Math::OdeState & | state | ) |

override virtual

Initialize the FemElement once everything has been set.

Parameters

  state | The state to initialize the FemElement with

Reimplemented from SurgSim::Physics::FemElement.

## initializeMembers()

void SurgSim::Physics::Fem3DElementTetrahedron::initializeMembers | ( |  | ) |

protected

Initializes variables needed before Initialize() is called.

## Member Data Documentation

## m_ai

std::array<double, 4> SurgSim::Physics::Fem3DElementTetrahedron::m_ai

protected

Shape functions coefficients Ni(x,y,z) = 1/6V ( ai + x.bi + y.ci + z.di )

## m_bi

std::array<double, 4> SurgSim::Physics::Fem3DElementTetrahedron::m_bi

protected

## m_ci

std::array<double, 4> SurgSim::Physics::Fem3DElementTetrahedron::m_ci

protected

## m_di

std::array<double, 4> SurgSim::Physics::Fem3DElementTetrahedron::m_di

protected

## m_Em

Eigen::Matrix<double, 6, 6> SurgSim::Physics::Fem3DElementTetrahedron::m_Em

protected

Elasticity material matrix (contains the elastic properties of the material)

## m_restVolume

double SurgSim::Physics::Fem3DElementTetrahedron::m_restVolume

protected

Shape functions: Tetrahedron rest volume.

## m_strain

Eigen::Matrix<double, 6, 12> SurgSim::Physics::Fem3DElementTetrahedron::m_strain

protected

Strain matrix.

## m_stress

Eigen::Matrix<double, 6, 12> SurgSim::Physics::Fem3DElementTetrahedron::m_stress

protected

Stress matrix.

## m_x0

Eigen::Matrix<double, 12, 1> SurgSim::Physics::Fem3DElementTetrahedron::m_x0

protected

The tetrahedon rest state.

The documentation for this class was generated from the following files:

- SurgSim/Physics/Fem3DElementTetrahedron.h
- SurgSim/Physics/Fem3DElementTetrahedron.cpp