Upgrade bindings to simpler API

Q-Minh · Jul 18, 2024 · c4557cc · c4557cc
1 parent f88550c
commit c4557cc
Show file tree

Hide file tree

Showing 20 changed files with 168 additions and 1,878 deletions.
diff --git a/bindings/pypbat/CMakeLists.txt b/bindings/pypbat/CMakeLists.txt
@@ -10,7 +10,6 @@ add_subdirectory(profiling)
 
 target_link_libraries(PhysicsBasedAnimationToolkit_Python
     PRIVATE
-    # PBAT_PyFem
     pybind11::headers
     Python::Module
 )
diff --git a/bindings/pypbat/fem/CMakeLists.txt b/bindings/pypbat/fem/CMakeLists.txt
@@ -1,104 +1,3 @@
-# add_library(PBAT_PyFem)
-# set_target_properties(PBAT_PyFem
-# PROPERTIES
-# FOLDER "PhysicsBasedAnimationToolkit/bindings/fem"
-# WINDOWS_EXPORT_ALL_SYMBOLS ON
-# )
-
-# list(APPEND _pbat_fem_types
-# "Gradient"
-# "HyperElasticPotential"
-# "Jacobian"
-# "LaplacianMatrix"
-# "LoadVector"
-# "MassMatrix"
-# "Mesh"
-# "ShapeFunctions"
-# )
-
-# set(_pbat_python_autogen_dir "gen")
-
-# foreach(_pbat_fem_type IN ITEMS ${_pbat_fem_types})
-# set(_pbat_python_fem_target "PBAT_PyFem_${_pbat_fem_type}")
-# add_library(${_pbat_python_fem_target})
-# set_target_properties(${_pbat_python_fem_target}
-# PROPERTIES
-# FOLDER "PhysicsBasedAnimationToolkit/bindings/fem/${_pbat_fem_type}"
-# WINDOWS_EXPORT_ALL_SYMBOLS ON
-# )
-# target_link_libraries(${_pbat_python_fem_target}
-# PUBLIC
-# pybind11::headers
-# Python::Module
-# PRIVATE
-# PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit
-# )
-
-# execute_process(
-# COMMAND ${Python_EXECUTABLE} bindings.py --cmake=1 --type=${_pbat_fem_type}
-# WORKING_DIRECTORY "${CMAKE_CURRENT_LIST_DIR}"
-# OUTPUT_VARIABLE _pbat_fem_bindings_impl
-# ERROR_VARIABLE _pbat_fem_bindings_error
-# RESULT_VARIABLE _pbat_bindings_exit_code
-# ECHO_ERROR_VARIABLE
-# )
-
-# if(NOT _pbat_bindings_exit_code EQUAL 0)
-# message(FATAL_ERROR "Failed to generate FEM binding implementations.")
-# endif()
-
-# target_sources(${_pbat_python_fem_target}
-# PUBLIC
-# FILE_SET api
-# TYPE HEADERS
-# BASE_DIRS ${CMAKE_CURRENT_LIST_DIR}
-# )
-
-# target_sources(${_pbat_python_fem_target}
-# PUBLIC
-# FILE_SET api
-# FILES
-# "${_pbat_python_autogen_dir}/${_pbat_fem_type}.h"
-# )
-
-# target_sources(${_pbat_python_fem_target}
-# PRIVATE
-# "${_pbat_python_autogen_dir}/${_pbat_fem_type}.cpp"
-# ${_pbat_fem_bindings_impl}
-# )
-
-# target_link_libraries(PBAT_PyFem
-# PRIVATE
-# ${_pbat_python_fem_target}
-# )
-# endforeach()
-
-# target_link_libraries(PBAT_PyFem
-# PUBLIC
-# pybind11::headers
-# Python::Module
-# PRIVATE
-# PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit
-# )
-# target_sources(PBAT_PyFem
-# PUBLIC
-# FILE_SET api
-# TYPE HEADERS
-# BASE_DIRS ${CMAKE_CURRENT_LIST_DIR}
-# )
-
-# target_sources(PBAT_PyFem
-# PUBLIC
-# FILE_SET api
-# FILES
-# "Fem.h"
-# )
-
-# target_sources(PBAT_PyFem
-# PRIVATE
-# "Fem.cpp"
-# )
-
 target_sources(PhysicsBasedAnimationToolkit_Python
     PUBLIC
     FILE_SET api

diff --git a/bindings/pypbat/fem/Gradient.cpp b/bindings/pypbat/fem/Gradient.cpp
@@ -47,9 +47,11 @@ void BindGradient(pybind11::module& m)
             pyb::init<Mesh const&, Eigen::Ref<MatrixX const> const&, int>(),
             pyb::arg("mesh"),
             pyb::arg("GNe"),
-            pyb::arg("quadrature_order") = 1)
+            pyb::arg("quadrature_order") = 1,
+            "Construct Gradient operator from mesh mesh, using precomputed shape function "
+            "gradients GNe at quadrature points given by quadrature rule of order quadrature_order")
         .def_readonly("dims", &Gradient::mDims)
-        .def_readonly("order", &Gradient::mOrder)
+        .def_readonly("order", &Gradient::mOrder, "Polynomial order of the gradient")
         .def_readonly("quadrature_order", &Gradient::mQuadratureOrder)
         .def_property_readonly("shape", &Gradient::Shape)
         .def("to_matrix", &Gradient::ToMatrix);

diff --git a/bindings/pypbat/fem/HyperElasticPotential.cpp b/bindings/pypbat/fem/HyperElasticPotential.cpp
@@ -182,7 +182,11 @@ void BindHyperElasticPotential(pybind11::module& m)
             pyb::arg("Y")                = 1e6,
             pyb::arg("nu")               = 0.45,
             pyb::arg("energy")           = EHyperElasticEnergy::StableNeoHookean,
-            pyb::arg("quadrature_order") = 1)
+            pyb::arg("quadrature_order") = 1,
+            "Construct a HyperElasticPotential on mesh mesh, given precomputed jacobian "
+            "determinants detJe and shape function gradients GNe at mesh element quadrature points "
+            "given by quadrature rule of order quadrature_order. The corresponding energy has "
+            "Young's modulus Y and Poisson's ratio nu.")
         .def(
             pyb::init<
                 Mesh const&,
@@ -198,9 +202,13 @@ void BindHyperElasticPotential(pybind11::module& m)
             pyb::arg("Y"),
             pyb::arg("nu"),
             pyb::arg("energy")           = EHyperElasticEnergy::StableNeoHookean,
-            pyb::arg("quadrature_order") = 1)
+            pyb::arg("quadrature_order") = 1,
+            "Construct a HyperElasticPotential on mesh mesh, given precomputed jacobian "
+            "determinants detJe and shape function gradients GNe at mesh element quadrature points "
+            "given by quadrature rule of order quadrature_order. The corresponding energy has "
+            "piecewise constant (at elements) Young's modulus Y and Poisson's ratio nu.")
         .def_readonly("dims", &HyperElasticPotential::mDims)
-        .def_readonly("order", &HyperElasticPotential::mOrder)
+        //.def_readonly("order", &HyperElasticPotential::mOrder)
         .def_readonly("quadrature_order", &HyperElasticPotential::mQuadratureOrder)
         .def("precompute_hessian_sparsity", &HyperElasticPotential::PrecomputeHessianSparsity)
         .def(
@@ -215,22 +223,30 @@ void BindHyperElasticPotential(pybind11::module& m)
         .def_property(
             "mue",
             [](HyperElasticPotential const& M) { return M.mue(); },
-            [](HyperElasticPotential& M, Eigen::Ref<VectorX const> const& mue) { M.mue() = mue; })
+            [](HyperElasticPotential& M, Eigen::Ref<VectorX const> const& mue) { M.mue() = mue; },
+            "Piecewise constant (per-element) vector of first Lame coefficients")
         .def_property(
             "lambdae",
             [](HyperElasticPotential const& M) { return M.mue(); },
             [](HyperElasticPotential& M, Eigen::Ref<VectorX const> const& lambdae) {
                 M.lambdae() = lambdae;
-            })
+            },
+            "Piecewise constant (per-element) vector of second Lame coefficients")
         .def_property_readonly(
             "UE",
-            [](HyperElasticPotential const& M) { return M.ElementPotentials(); })
+            [](HyperElasticPotential const& M) { return M.ElementPotentials(); },
+            "|#elements| vector of element hyper elastic potentials")
         .def_property_readonly(
             "GE",
-            [](HyperElasticPotential const& M) { return M.ElementGradients(); })
+            [](HyperElasticPotential const& M) { return M.ElementGradients(); },
+            "|#element nodes * dims|x|#elements| matrix of element hyper elastic potential "
+            "gradients")
         .def_property_readonly(
             "HE",
-            [](HyperElasticPotential const& M) { return M.ElementHessians(); })
+            [](HyperElasticPotential const& M) { return M.ElementHessians(); },
+            "|#element nodes * dims|x|#elements nodes * dims * #elements| matrix of element hyper "
+            "elastic "
+            "potential hessians")
         .def_property_readonly("shape", &HyperElasticPotential::Shape)
         .def("to_matrix", &HyperElasticPotential::ToMatrix);
 }

diff --git a/bindings/pypbat/fem/Jacobian.cpp b/bindings/pypbat/fem/Jacobian.cpp
@@ -26,7 +26,9 @@ void BindJacobian(pybind11::module& m)
             return detJe;
         },
         pyb::arg("mesh"),
-        pyb::arg("quadrature_order") = 1);
+        pyb::arg("quadrature_order") = 1,
+        "|#quad.pts.|x|#elements| matrix of element jacobian determinants at element quadrature "
+        "points");
 
     m.def(
         "inner_product_weights",
@@ -41,7 +43,9 @@ void BindJacobian(pybind11::module& m)
             return I;
         },
         pyb::arg("mesh"),
-        pyb::arg("quadrature_order") = 1);
+        pyb::arg("quadrature_order") = 1,
+        "|#quad.pts.|x|#elements| matrix of quadrature weights multiplied by jacobian determinants "
+        "at element quadrature points ");
 
     m.def(
         "inner_product_weights",
@@ -57,10 +61,12 @@ void BindJacobian(pybind11::module& m)
         },
         pyb::arg("mesh"),
         pyb::arg("detJe"),
-        pyb::arg("quadrature_order") = 1);
+        pyb::arg("quadrature_order") = 1,
+        "|#quad.pts.|x|#elements| matrix of quadrature weights multiplied by jacobian determinants "
+        "at element quadrature points");
 
     m.def(
-        "inner_product_weights",
+        "reference_positions",
         [](Mesh const& M,
            Eigen::Ref<IndexVectorX const> const& E,
            Eigen::Ref<MatrixX const> const& X,
@@ -76,7 +82,9 @@ void BindJacobian(pybind11::module& m)
         pyb::arg("E"),
         pyb::arg("X"),
         pyb::arg("max_iters") = 5,
-        pyb::arg("eps")       = 1e-10);
+        pyb::arg("eps")       = 1e-10,
+        "|#element dims| x |X.cols()| matrix of reference positions associated with domain points "
+        "X in corresponding elements E ");
 }
 
 } // namespace fem

diff --git a/bindings/pypbat/fem/Laplacian.cpp b/bindings/pypbat/fem/Laplacian.cpp
@@ -64,7 +64,12 @@ void BindLaplacian(pybind11::module& m)
             pyb::arg("detJe"),
             pyb::arg("GNe"),
             pyb::arg("dims")             = 1,
-            pyb::arg("quadrature_order") = 1)
+            pyb::arg("quadrature_order") = 1,
+            "Construct the symmetric part of the Laplacian operator on mesh mesh, using "
+            "precomputed jacobian determinants detJe and shape function gradients GNe evaluated at "
+            "quadrature points given by the quadrature rule of order quadrature_order. The "
+            "discretization is based on Galerkin projection. The dimensions dims can be set to "
+            "accommodate vector-valued functions.")
         .def_property(
             "dims",
             [](Laplacian const& L) { return L.dims(); },
@@ -76,7 +81,8 @@ void BindLaplacian(pybind11::module& m)
             [](Laplacian const& L) { return L.ElementLaplacians(); },
             [](Laplacian& L, Eigen::Ref<MatrixX const> const& deltaE) {
                 L.ElementLaplacians() = deltaE;
-            })
+            },
+            "|#element nodes|x|#element nodes * #elements| matrix of element Laplacians")
         .def_property_readonly("shape", &Laplacian::Shape)
         .def("to_matrix", &Laplacian::ToMatrix);
 }

diff --git a/bindings/pypbat/fem/MassMatrix.cpp b/bindings/pypbat/fem/MassMatrix.cpp
@@ -64,9 +64,14 @@ void BindMassMatrix(pybind11::module& m)
             pyb::init<Mesh const&, Eigen::Ref<MatrixX const> const&, Scalar, int, int>(),
             pyb::arg("mesh"),
             pyb::arg("detJe"),
-            pyb::arg("rho"),
-            pyb::arg("dims"),
-            pyb::arg("quadrature_order") = 1)
+            pyb::arg("rho") = 1.,
+            pyb::arg("dims") = 1,
+            pyb::arg("quadrature_order") = 1,
+            "Construct the mass matrix operator on mesh mesh, using "
+            "precomputed jacobian determinants detJe evaluated at "
+            "quadrature points given by the quadrature rule of order quadrature_order. The "
+            "dimensions dims can be set to accommodate vector-valued functions. rho is a uniform "
+            "mass density.")
         .def(
             pyb::init<
                 Mesh const&,
@@ -76,9 +81,14 @@ void BindMassMatrix(pybind11::module& m)
                 int>(),
             pyb::arg("mesh"),
             pyb::arg("detJe"),
-            pyb::arg("rho"),
-            pyb::arg("dims"),
-            pyb::arg("quadrature_order") = 1)
+            pyb::arg("rho") = 1.,
+            pyb::arg("dims") = 1,
+            pyb::arg("quadrature_order") = 1,
+            "Construct the mass matrix operator on mesh mesh, using "
+            "precomputed jacobian determinants detJe evaluated at "
+            "quadrature points given by the quadrature rule of order quadrature_order. The "
+            "dimensions dims can be set to accommodate vector-valued functions. rho is a piecewise "
+            "constant (per element) mass density.")
         .def_property(
             "dims",
             [](MassMatrix const& L) { return L.dims(); },
@@ -90,7 +100,8 @@ void BindMassMatrix(pybind11::module& m)
             [](MassMatrix const& M) { return M.ElementMassMatrices(); },
             [](MassMatrix& M, Eigen::Ref<MatrixX const> const& ME) {
                 M.ElementMassMatrices() = ME;
-            })
+            },
+            "|#element nodes| x |#elements nodes * #elements| matrix of element mass matrices")
         .def_property_readonly("shape", &MassMatrix::Shape)
         .def("to_matrix", &MassMatrix::ToMatrix);
 }

diff --git a/bindings/pypbat/fem/ShapeFunctions.cpp b/bindings/pypbat/fem/ShapeFunctions.cpp
@@ -26,7 +26,9 @@ void BindShapeFunctions(pybind11::module& m)
             return GN;
         },
         pyb::arg("mesh"),
-        pyb::arg("quadrature_order") = 1);
+        pyb::arg("quadrature_order") = 1,
+        "|#element nodes| x |#dims * #quad.pts. * #elements| matrix of shape functions at each "
+        "element quadrature point");
 
     m.def(
         "shape_function_gradients_at",
@@ -41,7 +43,9 @@ void BindShapeFunctions(pybind11::module& m)
         },
         pyb::arg("mesh"),
         pyb::arg("E"),
-        pyb::arg("Xi"));
+        pyb::arg("Xi"),
+        "|#element nodes| x |E.size() * mesh.dims| nodal shape function gradients at reference "
+        "points Xi");
 
     m.def(
         "shape_function_matrix",
@@ -56,7 +60,8 @@ void BindShapeFunctions(pybind11::module& m)
             return N;
         },
         pyb::arg("mesh"),
-        pyb::arg("quadrature_order") = 1);
+        pyb::arg("quadrature_order") = 1,
+        "|#elements * #quad.pts.| x |#nodes| shape function matrix");
 
     m.def(
         "shape_functions_at",
@@ -69,7 +74,8 @@ void BindShapeFunctions(pybind11::module& m)
             return N;
         },
         pyb::arg("mesh"),
-        pyb::arg("Xi"));
+        pyb::arg("Xi"),
+        "|#element nodes| x |Xi.cols()| matrix of nodal shape functions at reference points Xi");
 }
 
 } // namespace fem