opensurgsim
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
SurgSim::Physics::Fem3DElementCube Class Reference

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

#include <Fem3DElementCube.h>

Inheritance diagram for SurgSim::Physics::Fem3DElementCube:
SurgSim::Physics::FemElement MockFem3DElementCube

Public Member Functions

 Fem3DElementCube ()
 Constructor.
 
 Fem3DElementCube (std::array< size_t, 8 > nodeIds)
 Constructor. More...
 
 Fem3DElementCube (std::shared_ptr< FemElementStructs::FemElementParameter > elementData)
 Constructor for FemElement object factory. More...
 
void initialize (const SurgSim::Math::OdeState &state) override
 Initializes the element 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.
 
virtual ~FemElement ()
 Virtual destructor.
 
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) const
 Adds the element force (computed for a given state) to a complete system force vector F (assembly) More...
 
virtual void addForce (SurgSim::Math::Vector *F) const
 
virtual void addMass (SurgSim::Math::SparseMatrix *M, double scale) const
 Adds the element mass matrix M (computed for a given state) to a complete system mass matrix M (assembly) More...
 
virtual void addMass (SurgSim::Math::SparseMatrix *M) const
 
virtual void addDamping (SurgSim::Math::SparseMatrix *D, double scale) 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 addDamping (SurgSim::Math::SparseMatrix *D) const
 
virtual void addStiffness (SurgSim::Math::SparseMatrix *K, double scale) 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 addStiffness (SurgSim::Math::SparseMatrix *K) const
 
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, SurgSim::Math::Vector *extractedX, SurgSim::Math::Vector *acumulator) 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 T , int Opt, typename StorageIndex >
void assembleMatrixBlocks (const Eigen::Ref< const Math::Matrix > &subMatrix, const std::vector< size_t > &blockIds, size_t blockSize, Eigen::SparseMatrix< T, Opt, StorageIndex > *matrix) const
 Add a sub-matrix made of squared-blocks into a matrix that could be un-initialized. More...
 
template<typename T , int Opt, typename StorageIndex >
void assembleMatrixBlocksNoInitialize (const Eigen::Ref< const Math::Matrix > &subMatrix, const std::vector< size_t > &blockIds, size_t blockSize, Eigen::SparseMatrix< T, Opt, StorageIndex > *matrix) const
 Add a sub-matrix made of squared-blocks into a matrix that is already initialized. 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.
 
void buildConstitutiveMaterialMatrix (Eigen::Matrix< double, 6, 6 > *constitutiveMatrix)
 Build the constitutive material 6x6 matrix. More...
 
void computeStiffness (const SurgSim::Math::OdeState &state, Eigen::Matrix< double, 6, 24 > *strain, Eigen::Matrix< double, 6, 24 > *stress, SurgSim::Math::Matrix *k)
 Computes the cube stiffness matrix along with the strain and stress matrices. More...
 
void computeMass (const SurgSim::Math::OdeState &state, SurgSim::Math::Matrix *m)
 Computes the cube mass matrix. More...
 
void doUpdateFMDK (const Math::OdeState &state, int options) override
 Update the FemElement based on the given state. More...
 
void addStrainStressStiffnessAtPoint (const SurgSim::Math::OdeState &state, const SurgSim::Math::gaussQuadraturePoint &epsilon, const SurgSim::Math::gaussQuadraturePoint &eta, const SurgSim::Math::gaussQuadraturePoint &mu, Eigen::Matrix< double, 6, 24 > *strain, Eigen::Matrix< double, 6, 24 > *stress, SurgSim::Math::Matrix *k)
 Helper method to evaluate strain-stress and stiffness integral terms with a discrete sum using a Gauss quadrature rule. More...
 
void addMassMatrixAtPoint (const SurgSim::Math::OdeState &state, const SurgSim::Math::gaussQuadraturePoint &epsilon, const SurgSim::Math::gaussQuadraturePoint &eta, const SurgSim::Math::gaussQuadraturePoint &mu, SurgSim::Math::Matrix *m)
 Helper method to evaluate mass integral terms with a discrete sum using a Gauss quadrature rule. More...
 
void evaluateJ (const SurgSim::Math::OdeState &state, double epsilon, double eta, double mu, SurgSim::Math::Matrix33d *J, SurgSim::Math::Matrix33d *Jinv, double *detJ) const
 Helper method to evaluate matrix J = d(x,y,z)/d(epsilon,eta,mu) at a given 3D parametric location J expresses the 3D space coordinate frames variation w.r.t. More...
 
void evaluateStrainDisplacement (double epsilon, double eta, double mu, const SurgSim::Math::Matrix33d &Jinv, Eigen::Matrix< double, 6, 24 > *B) const
 Helper method to evaluate the strain-displacement matrix at a given 3D parametric location c.f. More...
 
double shapeFunction (size_t i, double epsilon, double eta, double mu) const
 Shape functions \(N_i(\epsilon, \eta, \mu) = (1\pm\epsilon)(1\pm\eta)(1\pm\mu)/8\). More...
 
double dShapeFunctiondepsilon (size_t i, double epsilon, double eta, double mu) const
 Shape functions derivative \(dN_i/d\epsilon(\epsilon, \eta, \mu) = \pm(1\pm\eta)(1\pm\mu)/8\). More...
 
double dShapeFunctiondeta (size_t i, double epsilon, double eta, double mu) const
 Shape functions derivative \(dN_i/d\eta(\epsilon, \eta, \mu) = \pm(1\pm\epsilon)(1\pm\mu)/8\). More...
 
double dShapeFunctiondmu (size_t i, double epsilon, double eta, double mu) const
 Shape functions derivative \(dN_i/d\mu(\epsilon, \eta, \mu) = \pm(1\pm\epsilon)(1\pm\eta)/8\). 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.
 
virtual void doInitializeFMDK ()
 Function to be overridden by the derived classes to initialize the f, M, D, K variables.
 

Protected Attributes

double m_restVolume
 Cube rest volume.
 
Eigen::Matrix< double, 24, 1 > m_elementRestPosition
 The cube rest state (nodes ordered by m_nodeIds)
 
Eigen::Matrix< double, 6, 24 > m_strain
 Strain matrix (usually noted \(\epsilon\))
 
Eigen::Matrix< double, 6, 24 > m_stress
 Stress matrix (usually noted \(\sigma\))
 
Eigen::Matrix< double, 6, 6 > m_constitutiveMaterial
 Constitutive material matrix (Hooke's law in this case) defines the relationship between stress and strain.
 
std::array< double, 8 > m_shapeFunctionsEpsilonSign
 
std::array< double, 8 > m_shapeFunctionsEtaSign
 
std::array< double, 8 > m_shapeFunctionsMuSign
 
- Protected Attributes inherited from SurgSim::Physics::FemElement
size_t m_numDofPerNode
 Number of degree of freedom per node for this element.
 
std::vector< size_t > m_nodeIds
 Node ids connected by this element.
 
SurgSim::Math::Vector m_f
 The force vector.
 
SurgSim::Math::Matrix m_K
 The stiffness matrix.
 
SurgSim::Math::Matrix m_M
 The mass matrix.
 
SurgSim::Math::Matrix m_D
 The damping matrix.
 
bool m_useDamping
 Flag to specify of the damping is used.
 
double m_rho
 Mass density (in Kg.m-3)
 
double m_E
 Young modulus (in N.m-2)
 
double m_nu
 Poisson ratio (unitless)
 

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 FactoryTypegetFactory ()
 

Detailed Description

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

Note
The stiffness property of the cube is derived from
http://www.colorado.edu/engineering/CAS/courses.d/AFEM.d/AFEM.Ch11.d/AFEM.Ch11.pdf
The mass property of the cube is derived from the kinetic energy computed on the cube's volume
(c.f. internal documentation on cube mass matrix computation for details).
Integral terms over the volume are evaluated using the Gauss-Legendre 2-points quadrature.
http://en.wikipedia.org/wiki/Gaussian_quadrature
Note that this technique is accurate for any polynomial evaluation up to degree 3.
In our case, the shape functions \(N_i\) are linear (of degree 1). So for exmaple,
in the mass matrix we have integral terms like \(\int_V N_i.N_j dV\), which are of degree 2.
Fem3DElementCube uses linear elasticity (not visco-elasticity), so it does not give any damping.

Constructor & Destructor Documentation

§ Fem3DElementCube() [1/2]

SurgSim::Physics::Fem3DElementCube::Fem3DElementCube ( std::array< size_t, 8 >  nodeIds)
explicit

Constructor.

Parameters
nodeIdsAn array of 8 node ids defining this cube element in an overall mesh
Note
It is required that getVolume() is positive, to do so, it needs (looking at the cube from
the exterior, face normal 'n' pointing outward):
the 1st 4 nodeIds (ABCD) should define any face CW i.e. (AB^AC or AB^AD or AC^AD).n < 0
the last 4 nodeIds (EFGH) should define the opposite face CCW i.e. (EF^EG or EF^EH or EG^EH).n > 0
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.

§ Fem3DElementCube() [2/2]

SurgSim::Physics::Fem3DElementCube::Fem3DElementCube ( std::shared_ptr< FemElementStructs::FemElementParameter elementData)
explicit

Constructor for FemElement object factory.

Parameters
elementDataA FemElement3D struct defining this cube element in an overall mesh
Note
It is required that getVolume() is positive, to do so, it needs (looking at the cube from
the exterior, face normal 'n' pointing outward):
the 1st 4 nodeIds (ABCD) should define any face CW i.e. (AB^AC or AB^AD or AC^AD).n < 0
the last 4 nodeIds (EFGH) should define the opposite face CCW i.e. (EF^EG or EF^EH or EG^EH).n > 0
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::AssertionFailureif nodeIds has a size different than 8

Member Function Documentation

§ addMassMatrixAtPoint()

void SurgSim::Physics::Fem3DElementCube::addMassMatrixAtPoint ( const SurgSim::Math::OdeState state,
const SurgSim::Math::gaussQuadraturePoint epsilon,
const SurgSim::Math::gaussQuadraturePoint eta,
const SurgSim::Math::gaussQuadraturePoint mu,
SurgSim::Math::Matrix m 
)
protected

Helper method to evaluate mass integral terms with a discrete sum using a Gauss quadrature rule.

Parameters
stateThe state to compute the evaluation with
epsilon,eta,muThe Gauss quadrature points to evaluate the data at
[out]mThe matrix in which to add the evaluations

§ addStrainStressStiffnessAtPoint()

void SurgSim::Physics::Fem3DElementCube::addStrainStressStiffnessAtPoint ( const SurgSim::Math::OdeState state,
const SurgSim::Math::gaussQuadraturePoint epsilon,
const SurgSim::Math::gaussQuadraturePoint eta,
const SurgSim::Math::gaussQuadraturePoint mu,
Eigen::Matrix< double, 6, 24 > *  strain,
Eigen::Matrix< double, 6, 24 > *  stress,
SurgSim::Math::Matrix k 
)
protected

Helper method to evaluate strain-stress and stiffness integral terms with a discrete sum using a Gauss quadrature rule.

Parameters
stateThe state to compute the evaluation with
epsilon,eta,muThe Gauss quadrature points to evaluate the data at
[out]strain,stress,kThe matrices in which to add the evaluations

§ buildConstitutiveMaterialMatrix()

void SurgSim::Physics::Fem3DElementCube::buildConstitutiveMaterialMatrix ( Eigen::Matrix< double, 6, 6 > *  constitutiveMatrix)
protected

Build the constitutive material 6x6 matrix.

Parameters
[out]constitutiveMatrixThe 6x6 constitutive material matrix

§ computeCartesianCoordinate()

SurgSim::Math::Vector SurgSim::Physics::Fem3DElementCube::computeCartesianCoordinate ( const SurgSim::Math::OdeState state,
const SurgSim::Math::Vector naturalCoordinate 
) const
overridevirtual

Computes a given natural coordinate in cartesian coordinates.

Parameters
stateThe state at which to transform coordinates
naturalCoordinateThe coordinates to transform
Returns
The resultant cartesian coordinates

Implements SurgSim::Physics::FemElement.

§ computeMass()

void SurgSim::Physics::Fem3DElementCube::computeMass ( const SurgSim::Math::OdeState state,
SurgSim::Math::Matrix m 
)
protected

Computes the cube mass matrix.

Parameters
stateThe state to compute the mass matrix from
[out]mThe mass matrix to store the result into

§ computeNaturalCoordinate()

SurgSim::Math::Vector SurgSim::Physics::Fem3DElementCube::computeNaturalCoordinate ( const SurgSim::Math::OdeState state,
const SurgSim::Math::Vector cartesianCoordinate 
) const
overridevirtual

Computes a natural coordinate given a global coordinate.

Parameters
stateThe state at which to transform coordinates
cartesianCoordinateThe coordinates to transform
Returns
The resultant natural coordinates

Implements SurgSim::Physics::FemElement.

§ computeStiffness()

void SurgSim::Physics::Fem3DElementCube::computeStiffness ( const SurgSim::Math::OdeState state,
Eigen::Matrix< double, 6, 24 > *  strain,
Eigen::Matrix< double, 6, 24 > *  stress,
SurgSim::Math::Matrix k 
)
protected

Computes the cube stiffness matrix along with the strain and stress matrices.

Parameters
stateThe state to compute the stiffness matrix from
[out]strain,stress,kThe strain, stress and stiffness matrices to store the result into

§ doUpdateFMDK()

void SurgSim::Physics::Fem3DElementCube::doUpdateFMDK ( const Math::OdeState state,
int  options 
)
overrideprotectedvirtual

Update the FemElement based on the given state.

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

Implements SurgSim::Physics::FemElement.

§ dShapeFunctiondepsilon()

double SurgSim::Physics::Fem3DElementCube::dShapeFunctiondepsilon ( size_t  i,
double  epsilon,
double  eta,
double  mu 
) const
protected

Shape functions derivative \(dN_i/d\epsilon(\epsilon, \eta, \mu) = \pm(1\pm\eta)(1\pm\mu)/8\).

Parameters
iThe node id (w.r.t. local element) to evaluate at
epsilon,eta,muThe 3D parametric coordinates each within \([-1 +1]\)
Returns
dNi/depsilon(epsilon, eta, mu)
Note
A check is performed on the nodeId i but not on the 3D parametric coordinates range
See also
N
m_shapeFunctionsEpsilonSign, m_shapeFunctionsEtaSign, m_shapeFunctionsMuSign

§ dShapeFunctiondeta()

double SurgSim::Physics::Fem3DElementCube::dShapeFunctiondeta ( size_t  i,
double  epsilon,
double  eta,
double  mu 
) const
protected

Shape functions derivative \(dN_i/d\eta(\epsilon, \eta, \mu) = \pm(1\pm\epsilon)(1\pm\mu)/8\).

Parameters
iThe node id (w.r.t. local element) to evaluate at
epsilon,eta,muThe 3D parametric coordinates each within \([-1 +1]\)
Returns
dNi/depsilon(epsilon, eta, mu)
Note
A check is performed on the nodeId i but not on the 3D parametric coordinates range
See also
N
m_shapeFunctionsEpsilonSign, m_shapeFunctionsEtaSign, m_shapeFunctionsMuSign

§ dShapeFunctiondmu()

double SurgSim::Physics::Fem3DElementCube::dShapeFunctiondmu ( size_t  i,
double  epsilon,
double  eta,
double  mu 
) const
protected

Shape functions derivative \(dN_i/d\mu(\epsilon, \eta, \mu) = \pm(1\pm\epsilon)(1\pm\eta)/8\).

Parameters
iThe node id (w.r.t. local element) to evaluate at
epsilon,eta,muThe 3D parametric coordinates each within \([-1 +1]\)
Returns
dNi/depsilon(epsilon, eta, mu)
Note
A check is performed on the nodeId i but not on the 3D parametric coordinates range
See also
N
m_shapeFunctionsEpsilonSign, m_shapeFunctionsEtaSign, m_shapeFunctionsMuSign

§ evaluateJ()

void SurgSim::Physics::Fem3DElementCube::evaluateJ ( const SurgSim::Math::OdeState state,
double  epsilon,
double  eta,
double  mu,
SurgSim::Math::Matrix33d J,
SurgSim::Math::Matrix33d Jinv,
double *  detJ 
) const
protected

Helper method to evaluate matrix J = d(x,y,z)/d(epsilon,eta,mu) at a given 3D parametric location J expresses the 3D space coordinate frames variation w.r.t.

parametric coordinates

Parameters
stateThe state to compute the evaluation with
epsilon,eta,muThe 3D parametric coordinates to evaluate the data at (within \([-1 +1]\))
[out]J,Jinv,detJThe J matrix with its inverse and determinant evaluated at (epsilon, eta, mu)

§ evaluateStrainDisplacement()

void SurgSim::Physics::Fem3DElementCube::evaluateStrainDisplacement ( double  epsilon,
double  eta,
double  mu,
const SurgSim::Math::Matrix33d Jinv,
Eigen::Matrix< double, 6, 24 > *  B 
) const
protected

Helper method to evaluate the strain-displacement matrix at a given 3D parametric location c.f.

http://www.colorado.edu/engineering/CAS/courses.d/AFEM.d/AFEM.Ch11.d/AFEM.Ch11.pdf for more details

Parameters
epsilon,eta,muThe 3D parametric coordinates to evaluate the data at (within \([-1 +1]\))
JinvThe inverse of matrix J (3D global coords to 3D parametric coords)
[out]BThe strain-displacement matrix

§ getVolume()

double SurgSim::Physics::Fem3DElementCube::getVolume ( const SurgSim::Math::OdeState state) const
overridevirtual

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

Parameters
stateThe state to compute the volume with
Returns
The volume of this element (in m-3)

Implements SurgSim::Physics::FemElement.

§ initialize()

void SurgSim::Physics::Fem3DElementCube::initialize ( const SurgSim::Math::OdeState state)
overridevirtual

Initializes the element once everything has been set.

Parameters
stateThe state to initialize the FemElement with
Note
We use the theory of linear elasticity, so this method precomputes the stiffness and mass matrices
The 8 node ids must be valid in the given state, if they aren't an ASSERT will be raised
The 8 node ids must define a cube with positive volume, if they don't an ASSERT will be raised
In order to do so (looking at the cube from the exterior, face normal 'n' pointing outward),
the 1st 4 nodeIds (ABCD) should define any face CW i.e. (AB^AC or AB^AD or AC^AD).n < 0
the last 4 nodeIds (EFGH) should define the opposite face CCW i.e. (EF^EG or EF^EH or EG^EH).n > 0
A warning will be logged in if this condition is not met, but the simulation will keep running.
Behavior will be undefined because of possible negative volume terms.

Reimplemented from SurgSim::Physics::FemElement.

§ shapeFunction()

double SurgSim::Physics::Fem3DElementCube::shapeFunction ( size_t  i,
double  epsilon,
double  eta,
double  mu 
) const
protected

Shape functions \(N_i(\epsilon, \eta, \mu) = (1\pm\epsilon)(1\pm\eta)(1\pm\mu)/8\).

\( \begin{array}{r | r r r} i & sign(\epsilon) & sign(\eta) & sign(\mu) \\ \hline 0 & -1 & -1 & -1 \\ 1 & +1 & -1 & -1 \\ 2 & +1 & +1 & -1 \\ 3 & -1 & +1 & -1 \\ 4 & -1 & -1 & +1 \\ 5 & +1 & -1 & +1 \\ 6 & +1 & +1 & +1 \\ 7 & -1 & +1 & +1 \end{array} \)

Parameters
iThe node id (w.r.t. local element) to evaluate at
epsilon,eta,muThe 3D parametric coordinates each within \([-1 +1]\)
Returns
Ni(epsilon, eta, mu)
Note
A check is performed on the nodeId i but not on the 3D parametric coordinates range
See also
m_shapeFunctionsEpsilonSign, m_shapeFunctionsEtaSign, m_shapeFunctionsMuSign
dNdepsilon, dNdeta, dNdmu

Member Data Documentation

§ m_shapeFunctionsEpsilonSign

std::array<double, 8> SurgSim::Physics::Fem3DElementCube::m_shapeFunctionsEpsilonSign
protected

Shape functions parameters \(N_i(\epsilon, \eta, \mu) = (1\pm\epsilon)(1\pm\eta)(1\pm\mu)/8 = (1+\epsilon.sign(\epsilon_i))(1+\eta.sign(\eta_i))(1+\mu.sign(\mu_i))/8 \textbf{ with } (\epsilon, \eta, \mu) \in [-1 +1]^3\)

We choose to only store the sign of epsilon, eta and mu for each shape functions.

See also
N

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