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 lefttoright 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 systemdependent 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 fullrank, nonsubspace integrator that is most like the integrators you see in other finite element codes. It uses NewtonRaphson
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 positiononly 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 nonlinear materials. Currently a variety of nonlinear 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 autogenerated 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 NewtonRaphson solves within the lowrank
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. VenantKirchoff 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 (CAREER0430528, EMTCompBio0621999), the National Institutes of Health (NIBIB/NIH R01EB006615), NSERC (Manycore Physically Based Simulations), the Alfred P. Sloan Foundation, and donations from Intel, Pixar, and Autodesk.




