Data Fields

Links

Methods

{
  "name": "UniformMass",
  "namespace": "sofa::component::mass",
  "module": "Sofa.Component.Mass",
  "include": "sofa/component/mass/UniformMass.h",
  "doc": "Compute a mass equally spread over the number of nodes.",
  "inherits": [
    "Mass"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_vertexMass",
      "type": "MassType",
      "xmlname": "vertexMass",
      "help": "If unspecified or wrongly set, the totalMass information is used."
    },
    {
      "name": "d_totalMass",
      "type": "SReal",
      "xmlname": "totalMass",
      "help": "If unspecified or wrongly set, the default value is used: totalMass = 1.0"
    },
    {
      "name": "d_showCenterOfGravity",
      "type": "bool",
      "xmlname": "showGravityCenter",
      "help": "display the center of gravity of the system"
    },
    {
      "name": "d_showAxisSize",
      "type": "float",
      "xmlname": "showAxisSizeFactor",
      "help": "factor length of the axis displayed (only used for rigids)"
    },
    {
      "name": "d_computeMappingInertia",
      "type": "bool",
      "xmlname": "compute_mapping_inertia",
      "help": "to be used if the mass is placed under a mapping"
    },
    {
      "name": "d_showInitialCenterOfGravity",
      "type": "bool",
      "xmlname": "showInitialCenterOfGravity",
      "help": "display the initial center of gravity of the system"
    },
    {
      "name": "d_showX0",
      "type": "bool",
      "xmlname": "showX0",
      "help": "display the rest positions"
    },
    {
      "name": "d_localRange",
      "type": "type::Vec<2, int>",
      "xmlname": "localRange",
      "help": "are discarded (useful for parallelization using mesh partitioning)"
    },
    {
      "name": "d_preserveTotalMass",
      "type": "bool",
      "xmlname": "preserveTotalMass",
      "help": "Prevent totalMass from decreasing when removing particles."
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "constructor_message",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "setMass",
      "return_type": "void",
      "params": [
        {
          "name": "d_vertexMass",
          "type": "const MassType &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getVertexMass",
      "return_type": "const MassType &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMass",
      "return_type": "const MassType &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTotalMass",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setTotalMass",
      "return_type": "void",
      "params": [
        {
          "name": "m",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setFileMass",
      "return_type": "void",
      "params": [
        {
          "name": "file",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getFileMass",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "loadRigidMass",
      "return_type": "void",
      "params": [
        {
          "name": "filename",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initDefaultImpl",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkVertexMass",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initFromVertexMass",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTotalMass",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initFromTotalMass",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateFromTotalMass",
      "return_type": "sofa::core::objectmodel::ComponentState",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateFromVertexMass",
      "return_type": "sofa::core::objectmodel::ComponentState",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMDx",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "f",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dx",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "factor",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "accFromF",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "a",
          "type": "DataVecDeriv &"
        },
        {
          "name": "f",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "f",
          "type": "DataVecDeriv &"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "v",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getKineticEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "d_v",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMomentum",
      "return_type": "type::Vec6",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "v",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMDxToVector",
      "return_type": "void",
      "params": [
        {
          "name": "resVect",
          "type": "linearalgebra::BaseVector *"
        },
        {
          "name": "dx",
          "type": "const VecDeriv *"
        },
        {
          "name": "mFact",
          "type": "SReal"
        },
        {
          "name": "offset",
          "type": "unsigned int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addGravityToV",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "d_v",
          "type": "DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mat",
          "type": "sofa::linearalgebra::BaseMatrix *"
        },
        {
          "name": "mFact",
          "type": "SReal"
        },
        {
          "name": "offset",
          "type": "unsigned int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildMassMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "matrices",
          "type": "sofa::core::behavior::MassMatrixAccumulator *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildStiffnessMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "core::behavior::StiffnessMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildDampingMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "core::behavior::DampingMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getElementMass",
      "return_type": "SReal",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getElementMass",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        },
        {
          "name": "m",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isDiagonal",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "parse",
      "return_type": "void",
      "params": [
        {
          "name": "arg",
          "type": "sofa::core::objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `UniformMass` component in the SOFA framework is designed to compute mass values uniformly distributed across all nodes within a mechanical model. This class, which inherits from `sofa::core::behavior::Mass`, is part of the Sofa.Component.Mass module and supports various data types including Rigid2/3 Types and Vec3 Types. Its primary role is to manage and apply consistent mass values throughout the simulation.\n\n### Interactions with Other Components\n- **BaseMeshTopology**: `UniformMass` interacts with a topology container (linked via `l_topology`) for information about nodes, indices, and other topological data that are essential for applying mass uniformly across these nodes. The component also maintains indices of local DOFs that can be used selectively in computations.\n\n### Data Fields\n- **vertexMass**: Specifies the mass value for each node (default is 1). This field takes precedence if set over `totalMass` unless both are specified, in which case `totalMass` overrides.\n- **totalMass**: Represents the cumulative mass of all nodes. If unspecified or incorrect, a default value of 1.0 is used. It can be derived from `vertexMass` and the number of nodes if `vertexMass` is set.\n\n### Practical Usage Guidance\n- To initialize mass uniformly, specify either `vertexMass` or `totalMass`. The component automatically computes the other based on the number of nodes.\n- Use `showGravityCenter`, `showAxisSizeFactor`, `showInitialCenterOfGravity`, and `compute_mapping_inertia` to control visualizations and additional behaviors as needed.\n- When adjusting mass values, ensure they remain positive and check for consistency using methods like `checkVertexMass()` and `initFromTotalMass()`. If the mass information is invalid or incorrectly set, warnings will be issued.",
  "maths": "The `UniformMass` component in the SOFA framework is designed to compute mass values that are uniformly distributed over all nodes within a mechanical model. It implements the concept of a constant mass distribution, where each node has an identical mass value. This component plays a crucial role in the FEM simulation pipeline, particularly in the assembly phase and time integration stages.\n\n### Governing Equations and Operators\nThe `UniformMass` contributes to the following components:\n- **Mass Matrix (M):** The global mass matrix is assembled from local contributions of each element. For a uniform mass distribution, the mass at each node is constant, denoted as \\( m_{node} \\). This results in a diagonal mass matrix where each diagonal entry corresponds to one node's mass.\n\n\\[\nM =\n\\begin{pmatrix}\n    m_1 & 0 & \\cdots & 0 \\\\\n    0 & m_2 & \\ddots & \\vdots \\\\\n    \\vdots & \\ddots & \\ddots & 0 \\\\\n    0 & \\cdots & 0 & m_n\n\\end{pmatrix}\n\\]\n\n- **Internal Force (f_{int}):** The component also manages the computation of internal forces, including gravity. For each node, if there is a uniform gravitational field \\( g \\), the potential energy and internal force due to gravity can be computed as follows:\n\n\\[\ng = \\begin{pmatrix}\n    g_x \\\\\n    g_y \\\\\n    g_z\n\\end{pmatrix}\n\\]\n\nThe internal force at each node is given by:\n\n\\[\nf_{int}^{(i)} = m_i g\n\\]\n\n- **Residual (R):** The residual equation for the nonlinear system includes contributions from mass and forces. For a uniform mass distribution, the contribution of the mass matrix to the residual can be written as:\n\n\\[\nR(x_{n+1}) = M \\frac{x_{n+1} - x_n}{\\Delta t} - \\Delta t f_{int}(x_{n+1}) - \\Delta t f_{ext}\n\\]\n\n### Constitutive and Kinematic Laws Involved\n- **Mass Distribution:** The `UniformMass` component assumes a constant mass value across all nodes. This simplifies the formulation of the mass matrix, making it diagonal.\n\n- **Gravity Potential Energy:** If gravity is considered, the potential energy \\( V(x) \\) at each node due to gravity can be computed as:\n\n\\[\nV(x_i) = -m_i g \\cdot x_i \n\\]\n\n### Role in the Global FEM Pipeline\n- **Assembly Phase:** During assembly, `UniformMass` contributes to building the global mass matrix by setting each diagonal entry to the node's mass value. It also handles internal forces due to gravity.\n\n- **Time Integration:** In time integration schemes (e.g., implicit Euler), the mass matrix is used in computing the acceleration and updating the state variables. The uniform distribution simplifies this process, making it efficient.\n\n### Numerical Methods or Discretization Choices\nThe `UniformMass` component discretizes the mass uniformly across nodes, leading to a diagonal mass matrix. This simplification facilitates faster computation during both assembly and time integration steps. It also supports various data types (e.g., Rigid3Types, Vec3Types) and can handle different dimensions of mechanical models.\n\n### Integration into Variational / Lagrangian Mechanics Framework\nThe `UniformMass` component fits into the broader variational framework by ensuring that each node has a consistent mass value. This ensures physical consistency in the simulation, maintaining conservation properties such as energy or momentum. The uniform distribution simplifies the numerical evaluation of integrals and matrices, making it suitable for both real-time and high-fidelity simulations.\n\nOverall, `UniformMass` provides a simple yet powerful way to distribute mass uniformly across nodes, contributing to efficient and accurate FEM simulations within the SOFA framework.",
  "abstract": "The `UniformMass` component computes mass values uniformly distributed across all nodes within a mechanical model, ensuring consistent mass distribution throughout the simulation.",
  "sheet": "# UniformMass\n\n## Overview\nThe `UniformMass` component is part of the Sofa.Component.Mass module and inherits from `sofa::core::behavior::Mass`. It manages and applies uniform mass values to each node in the simulation. This ensures that all nodes have consistent mass distribution, which is crucial for accurate FEM simulations.\n\n## Parameters and Data\nThe significant data fields exposed by the component include:\n- **vertexMass**: Specifies the mass value for each node (default is 1). If set, it takes precedence over `totalMass` unless both are specified, in which case `totalMass` overrides.\n- **totalMass**: Represents the cumulative mass of all nodes. If unspecified or incorrect, a default value of 1.0 is used. It can be derived from `vertexMass` and the number of nodes if `vertexMass` is set.\n- **showGravityCenter**: Displays the center of gravity of the system (default is false).\n- **showAxisSizeFactor**: Factor length of the axis displayed for rigid bodies (default is 1.0).\n- **compute_mapping_inertia**: Used when the mass is placed under a mapping (default is false).\n- **showInitialCenterOfGravity**: Displays the initial center of gravity of the system (default is false).\n- **showX0**: Displays the rest positions (default is false).\n- **localRange**: Specifies the range of local DOFs that can be used selectively in computations.\n- **preserveTotalMass**: Prevents `totalMass` from decreasing when removing particles (default is false)."
}