compas-dev · tomvanmele · May 6, 2025 · May 4, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,8 +18,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-* Nanobind for ShapeOp solver.
-* Currently constraints: `ShapeOp::ClosenessConstraint`, `ShapeOp::EdgeStrainConstraint`, `ShapeOp::GravityForce`, `ShapeOp::ClosenessConstraint`, `ShapeOp::NormalForce`.
+* Implemented zero-copy integration between Python (NumPy) and C++ (Eigen/ShapeOp).
+* Constraints: ClosenessConstraint (with target position variant), EdgeStrainConstraint, ShrinkingEdgeConstraint, CircleConstraint, PlaneConstraint, BendingConstraint, SimilarityConstraint, RegularPolygonConstraint, ShapeConstraint
+* Forces: VertexForce, NormalForce, GravityForce
 
 ### Changed
 

diff --git a/docs/_images/PLACEHOLDER b/docs/_images/PLACEHOLDER
diff --git a/docs/_images/bending_constraint.png b/docs/_images/bending_constraint.png
diff --git a/docs/_images/circularization.gif b/docs/_images/circularization.gif
diff --git a/docs/_images/closeness_constraint_with_target.png b/docs/_images/closeness_constraint_with_target.png
diff --git a/docs/_images/face_normal_force.gif b/docs/_images/face_normal_force.gif
diff --git a/docs/_images/mesh_regularization.gif b/docs/_images/mesh_regularization.gif
diff --git a/docs/_images/plane_projection.gif b/docs/_images/plane_projection.gif
diff --git a/docs/_images/vertex_force_and_closeness_constraint.gif b/docs/_images/vertex_force_and_closeness_constraint.gif
diff --git a/docs/api/compas_shapeop.rst b/docs/api/compas_shapeop.rst
@@ -4,6 +4,68 @@ compas_shapeop
 
 .. currentmodule:: compas_shapeop
 
+Classes
+=======
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    Solver
+
+Functions and Methods
+=====================
+
+Mesh Integration
+----------------
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    Solver.from_mesh
+    Solver.add_mesh_edge_strain_constraint
+    Solver.add_mesh_vertex_force
+
+Constraints
+-----------
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    Solver.add_closeness_constraint
+    Solver.add_closeness_constraint_with_position
+    Solver.add_edge_strain_constraint
+    Solver.add_shrinking_edge_constraint
+    Solver.add_circle_constraint
+    Solver.add_plane_constraint
+    Solver.add_similarity_constraint
+    Solver.add_regular_polygon_constraint
+    Solver.add_bending_constraint
+    Solver.add_shape_constraint
+
+Forces
+------
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    Solver.add_vertex_force
+    Solver.add_normal_force_with_faces
+    Solver.add_gravity_force
+
+Core Methods
+------------
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    Solver.points
+    Solver.init
+    Solver.solve
 
 .. toctree::
     :maxdepth: 1
diff --git a/docs/devguide.rst b/docs/devguide.rst
@@ -0,0 +1,14 @@
+********************************************************************************
+Development Guide
+********************************************************************************
+
+.. toctree::
+    :maxdepth: 1
+
+    devguide/overview
+    devguide/compiler
+    devguide/conda_environment
+    devguide/contribute
+    devguide/cmake_configuration
+    devguide/types
+    devguide/style
diff --git a/docs/devguide/cmake_configuration.rst b/docs/devguide/cmake_configuration.rst
@@ -0,0 +1,105 @@
+********************************************************************************
+CMake Configuration
+********************************************************************************
+
+The COMPAS ShapeOp extension is built with CMake, which configures and generates the C++ build system. The main ``CMakeLists.txt`` file contains all the necessary configuration to build the ShapeOp library and its Python bindings.
+
+Project Structure
+-----------------
+
+The CMake configuration is organized as follows:
+
+1. Basic project configuration and compiler options
+2. Dependency handling (Eigen, nanobind, OpenMP)
+3. ShapeOp library compilation
+4. Precompiled headers setup
+5. Python module definition and linking
+
+Build Options
+-------------
+
+The CMakeLists.txt file provides several options to customize the build:
+
+.. code-block:: cmake
+
+    option(ENABLE_PRECOMPILED_HEADERS "Enable precompiled headers" ON)
+    option(FAST_COMPILE "Optimize for faster compilation (-O0) vs execution (-O3)" OFF)
+    option(USE_OPENMP "Enable OpenMP support for parallel processing" ON)
+
+- ``ENABLE_PRECOMPILED_HEADERS``: Enable precompiled headers for faster compilation (default: ON)
+- ``FAST_COMPILE``: Optimize for faster compilation time with -O0 instead of faster execution with -O3 (default: OFF)
+- ``USE_OPENMP``: Enable OpenMP for parallel constraint solving (default: ON)
+
+Dependencies
+------------
+
+The project has several external dependencies:
+
+- **Eigen**: A header-only C++ library for linear algebra that is automatically downloaded if not already installed
+- **nanobind**: A lightweight library for creating Python bindings, used to expose the C++ ShapeOp implementation to Python
+- **OpenMP**: An optional dependency for parallel processing, which significantly improves performance for large meshes
+
+ShapeOp Library
+---------------
+
+The core ShapeOp library is built as a static library:
+
+.. code-block:: cmake
+
+    add_library(shapeop STATIC
+      # Core ShapeOp files
+      ${SHAPEOP_SRC_DIR}/Constraint.cpp
+      ${SHAPEOP_SRC_DIR}/Force.cpp
+      ${SHAPEOP_SRC_DIR}/LSSolver.cpp
+      ${SHAPEOP_SRC_DIR}/Solver.cpp
+      # Custom constraints/forces
+      ${SHAPEOP_SRC_DIR}/custom_constraints/normalforce.cpp
+    )
+
+This library contains both the core ShapeOp implementation and custom constraints/forces specific to COMPAS ShapeOp.
+
+Python Module
+-------------
+
+The Python module is built using nanobind:
+
+.. code-block:: cmake
+
+    nanobind_add_module(
+      _shapeop
+      STABLE_ABI
+      NB_STATIC
+      src/shapeop.cpp
+    )
+
+The module is named ``_shapeop`` and is linked against the ShapeOp static library. It uses the stable ABI to ensure compatibility across Python versions.
+
+Installation
+------------
+
+The installation target installs the module to the ``compas_shapeop`` package directory:
+
+.. code-block:: cmake
+
+    install(TARGETS _shapeop LIBRARY DESTINATION compas_shapeop)
+
+This allows the Python frontend to import the C++ module as ``from compas_shapeop import _shapeop``.
+
+Adding New Constraints or Forces
+--------------------------------
+
+To add a new constraint or force:
+
+1. Add the C++ implementation to ``src/shapeop/`` or ``src/shapeop/custom_constraints/``
+2. Add the file to the ``shapeop`` library in ``CMakeLists.txt``
+3. Expose the new constraint/force in ``src/shapeop.cpp``
+4. Create a Python wrapper in ``src/compas_shapeop/shapeop.py``
+
+Build Process
+-------------
+
+The build process is handled by scikit-build-core, which manages the CMake configuration and build process during Python package installation. When you run ``pip install -e .``, scikit-build-core automatically:
+
+1. Runs CMake to configure the build
+2. Builds the C++ extension
+3. Installs it alongside the Python files
diff --git a/docs/devguide/compiler.rst b/docs/devguide/compiler.rst
@@ -0,0 +1,46 @@
+********************************************************************************
+Compiler Requirements
+********************************************************************************
+
+Before installing COMPAS libigl, you need to ensure you have the appropriate C++ compiler setup for your operating system:
+
+Windows
+-------
+
+* Install Visual Studio Build Tools (2022 or newer)
+* During installation, select "Desktop development with C++"
+* No additional PATH settings are required as CMake will automatically find the compiler
+* Note: Due to Windows max/min macro conflicts, we use #define NOMINMAX before including Windows headers
+
+macOS
+-----
+
+* Install Xcode Command Line Tools:
+
+  .. code-block:: bash
+
+      xcode-select --install
+
+* The clang compiler will be automatically available after installation
+
+Linux
+-----
+
+* Install GCC and related build tools. On Ubuntu/Debian:
+
+  .. code-block:: bash
+
+      sudo apt-get update
+      sudo apt-get install build-essential
+
+* On RHEL/Fedora:
+
+  .. code-block:: bash
+
+      sudo dnf groupinstall "Development Tools"
+
+* Alternatively, when using conda, you can install the C++ compiler through conda:
+
+  .. code-block:: bash
+
+      conda install gxx_linux-64
diff --git a/docs/devguide/conda_environment.rst b/docs/devguide/conda_environment.rst
@@ -0,0 +1,24 @@
+********************************************************************************
+Conda Environment
+********************************************************************************
+
+There are two ways to set up the development environment:
+
+Using environment.yml (recommended)
+-----------------------------------
+
+.. code-block:: bash
+
+    conda env create -f environment.yml
+    conda activate compas_shapeop
+
+Manual setup
+------------
+
+.. code-block:: bash
+
+    conda create -n compas_shapeop -c conda-forge python=3.9 compas -y
+    pip install -r requirements-dev.txt
+    pip install --no-build-isolation -ve . -Ceditable.rebuild=true
+
+Both methods will create and configure the same development environment.