lsdo_function_spaces

lsdo_function_spaces is a pure-Python library for constructing continuous, high-dimensional, differentiable function representations (B-splines, tensor-product splines, scattered data spaces, and multivariate polynomials) tailored for gradient-based Multidisciplinary Design Optimization (MDO) and scientific computing.

📖 Online Documentation: https://lsdo-function-spaces.readthedocs.io

Developed by the Large-Scale Design Optimization (LSDO) Lab at the University of California, San Diego.

Key Features

• Differentiable Function Spaces: Unifies Cox-de Boor B-spline curves, surfaces, and volumes, Shepard inverse distance weighting (IDW), radial basis functions (RBF), and multivariate polynomials under an extensible functional abstraction.
• 100% Pure Python & JAX Accelerated: Zero Cython or C compiler dependencies. High-performance vectorized evaluation and projection algorithms implemented cleanly in NumPy with optional JAX JIT acceleration.
• Vectorized Inverse Point Projection: Robust, vectorized Gauss-Newton and Levenberg-Marquardt algorithms with active-set bounds handling for projecting point clouds onto parametric spline curves, surfaces, and volumes.
• End-to-End CSDL Graph Integration: Custom Vector-Jacobian Products (VJPs) and automatic differentiation through csdl_alpha, enabling exact analytic adjoint sensitivities across complex computational graphs.
• Interactive & Headless 3D Visualization: Native PyVista support for visualizing spline control meshes, evaluated surface geometries, and discrete point clouds.

Architecture Overview

Quickstart

Creating and Evaluating a B-spline Surface

import numpy as np
import csdl_alpha as csdl
from lsdo_function_spaces import BSplineSpace, Function

# 1. Define a 2D B-spline function space (degrees 3x3, 6x6 control points)
space = BSplineSpace(
    num_dimensions=2,
    order=(4, 4),
    num_coefficients=(6, 6),
)

# 2. Assign control point coefficients (e.g. parabolic saddle surface)
u = np.linspace(0, 1, 6)
v = np.linspace(0, 1, 6)
U, V = np.meshgrid(u, v, indexing="ij")
coefficients = np.stack([U, V, U**2 - V**2], axis=-1).reshape(-1, 3)

func = Function(space=space, coefficients=coefficients)

# 3. Evaluate surface at query parametric coordinates
eval_pts = np.array([
    [0.2, 0.3],
    [0.5, 0.5],
    [0.8, 0.9],
])
physical_coords = func.evaluate(eval_pts)
print("Evaluated physical coordinates:\n", physical_coords)

Inverse Parametric Point Projection

import numpy as np
from lsdo_function_spaces.core.spaces.non_cython_bsplines.b_spline_patch_projection_optimized import (
    project_points_lm_numpy,
    LMParams,
)

# Project arbitrary 3D points onto a B-spline surface patch
points = np.array([[0.25, 0.35, 0.1]])
u0s = np.array([[0.5, 0.5]])  # Initial parametric guess

u_opt, converged, lam, res = project_points_lm_numpy(
    points=points,
    u0s=u0s,
    coeffs=coefficients,
    degrees=(3, 3),
    knot_vectors=space.knot_vectors,
    params=LMParams(max_iter=50, tol_grad=1e-8),
)
print("Converged parametric coordinate:", u_opt)

Installation

Prerequisites & Installation

lsdo_function_spaces requires Python $\ge 3.9$ and standard scientific Python packages:

# 1. Install prerequisites
pip install numpy scipy jax networkx
pip install git+https://github.com/LSDOlab/CSDL_alpha.git@dev_andrew

# 2. Install lsdo_function_spaces (User)
pip install lsdo_function_spaces
# Or install development version directly from GitHub:
pip install git+https://github.com/LSDOlab/lsdo_function_spaces.git

For Developers

Clone the repository and install in editable mode with testing and documentation dependencies:

git clone https://github.com/LSDOlab/lsdo_function_spaces.git
cd lsdo_function_spaces
pip install -e ".[test,docs]"

Testing

Run the full test suite with coverage:

pytest -v tests/ --cov=lsdo_function_spaces --cov-report=term-missing

For environments without a physical display (e.g. CI runners), run with xvfb:

xvfb-run --auto-servernum pytest -v tests/

Documentation

Official documentation, API references, tutorials, and mathematical foundations are hosted online at lsdo-function-spaces.readthedocs.io.

To build the HTML documentation locally:

sphinx-build -b html docs docs/_build/html -q -W

View the generated documentation by opening docs/_build/html/index.html in any web browser.

License

This project is licensed under the terms of the GNU Lesser General Public License v3.0 (LGPL-3.0).