Cubica: a toolkit for subspace deformations


Coding Standards
  • All class names are in all capital letters, with underscores separating words, e.g. TET_MESH and SUBSPACE_INTEGRATOR.
  • All member variables begin with an underscore, e.g. _gravity, _position, _velocity.
  • All variable names start with a lowercase letter, and name containing multiple words capitalize the first letter in each subsequent word, e.g. totalSteps, currentTiming. This is so that a left-to-right scan of code will make it immediately obvious that the token is not a class name.
  • Function names follow the same convention as variable names, e.g. stepImplicit(), timingBreakdown().
  • 'Real' is used instead of 'float' and 'double'. 'Real' is defined using a macro in SETTINGS.h. While this could have been accomplished with templates as well, it seemed overkill to do so for only two types.
  • All tabs are two spaces.

Code Organization

The code is separated into the main source code, the src directory and its subdirectories, and the individual tools that call it, in the projects directory. Note that each projects subdirectory contains operating system-dependent Makefiles that can be called individually if you only want to make a single project.

Important Classes

  • TET_MESH is the base class for all tetrahedral meshes. The vertex positions are stored in _vertices and the tetrahedra are stored in _tets. The tetrahedra contain pointers into _vertices in lieu of duplicating the position data. The vector _x is a flattened out version of the vertex displacements. The function updateFullMesh will update all the vertex positions based on the displacements in _x.
  • FULLSPACE_INTEGRATOR is a full-rank, non-subspace integrator that is most like the integrators you see in other finite element codes. It uses Newton-Raphson iteration to solve for the dynamics of a given TET_MESH. The functions of most interest are:
    • stepSparseImplicitInvertible - this uses implicit Newmark to step the system forward in time. The MATERIAL that the tet mesh is composed of is assumed to use the invertible element technology from these SCA 2004 and SCA 2005 papers.
    • stepSparseQuasistaticInvertible - this performs a position-only solve that assumes the dynamics (velocity and acceleration) are negligible. The MATERIAL is again assumed to be invertible.
  • MATERIAL is an abstract class for arbitrary non-linear materials. Currently a variety of non-linear materials are supported, which are in the subclasses STVK, ARRUCA_BOYCE, MOONEY_RIVLIN, and NEO_HOOKEAN. A material can be made invertible by wrapping it with the INVERTIBLE class, which intercepts the appropriate material calls and applies inversion handling to them. Note that much of the code in the material classes where auto-generated from Matlab, and the Matlab scripts are available in the MATERIAL.h file.
  • SUBSPACE_TET_MESH is a subclass of TET_MESH and contains a reduced coordinate basis and position. These are respectively stored in _UBasis and _q. Many TET_MESH functions are overloaded to pull position data from _q instead of _x.
  • SUBSPACE_INTEGRATOR is the subspace equivalent of FULLSPACE_INTEGRATOR, and performs Newton-Raphson solves within the low-rank subspace specified by a given SUBSPACE_TET_MESH. The two functions corresponding to the two functions in FULLSPACE_INTEGRATOR described above are stepInvertibleImplicit and stepInvertibleQuasistatic. The solver assumes that a cubature scheme has been computed for the SUBSPACE_TET_MESH. The analytic reduced St. Venant-Kirchoff model from Barbic and James 2005 is currently not supported.
  • CUBATURE_GENERATOR computes the cubature scheme described in our SIGGRAPH Asia 2008 paper for a given SUBSPACE_TET_MESH. If a subspace basis _UBasis has not been computed for a mesh using PCA or ArpackLMA, it will try to compute a basis using SLEPc. Our experience is that ARPACK is much faster however, so we recommend using ArpackLMA.
  • PARTITIONED_TET_MESH is a tetrahedral mesh that has been divided into "body parts". The "cloned" vertices between the partitions, as well as the correspondence between the partitions and the original uncut mesh are tracked by this class. The class is further subclassed into PARTITIONED_SUBSPACE_TET_MESH, which attaches a subspace basis to each tetrahedral mesh, and PARTITIONED_SKINNED_SUBSPACE_TET_MESH, which attaches a skeleton and bones to each body part. This last class is the one that is ultimately used in the Cubica Armadillo example.
  • SUBSPACE_MULTIBODY_INTEGRATOR implements the skinned integrator described in the SCA 2011 paper. It handles all the multibody aspects of the integration, and applies the Fast Sandwich Transform (FST) described in that paper. The class that explicitly implements the FST is SANDWICH_TRANSFORM, and it is instantiated within this class. The integrator called in the Cubica Armadillo example is this integrator.

Cubica was written by Theodore Kim, with contributions from Doug James, Steven An, Jeff Chadwick, and Alan Bandurka.

This work was supported in part by the National Science Foundation (CAREER-0430528, EMTCompBio-0621999), the National Institutes of Health (NIBIB/NIH R01EB006615), NSERC (Many-core Physically Based Simulations), the Alfred P. Sloan Foundation, and donations from Intel, Pixar, and Autodesk.