lsdo-function-spaces 1.0.0__py3-none-any.whl

lsdo_function_spaces/utils/plotting_functions.py

@@ -0,0 +1,357 @@
+
+
+
+import numpy as np
+import pyvista as pv
+from typing import Union
+
+
+def _normalize_points(points: np.ndarray) -> np.ndarray:
+    if points.shape[-1] > 3:
+        raise ValueError(
+            'The points must have 3 or fewer physical dimensions (the size of the last axis).'
+            f' The provided points have {points.shape[-1]} physical dimensions. You probably want to reshape.'
+        )
+    points = points.reshape((points.size // points.shape[-1], points.shape[-1]))
+    if points.shape[-1] == 1:
+        points = np.hstack((points, np.zeros((points.shape[0], 2))))
+    elif points.shape[-1] == 2:
+        points = np.hstack((points, np.zeros((points.shape[0], 1))))
+    return points
+
+
+def _normalize_grid(points: np.ndarray) -> np.ndarray:
+    if points.shape[-1] > 3:
+        raise ValueError(
+            'The points must have 3 or fewer physical dimensions (the size of the last axis).'
+            f' The provided points have {points.shape[-1]} physical dimensions. You probably want to reshape.'
+        )
+    if points.shape[-1] == 1:
+        zeros = np.zeros(points.shape[:-1] + (2,))
+        points = np.concatenate((points, zeros), axis=-1)
+    elif points.shape[-1] == 2:
+        zeros = np.zeros(points.shape[:-1] + (1,))
+        points = np.concatenate((points, zeros), axis=-1)
+    return points
+
+
+def _extract_scalars(color: np.ndarray, num_points: int):
+    if color.ndim == 1:
+        if color.shape[0] != num_points:
+            raise ValueError("Color array length must match number of points.")
+        return color, False
+    if color.ndim == 2 and color.shape[0] == num_points:
+        if color.shape[1] == 1:
+            return color.reshape(-1), False
+        if color.shape[1] == 3:
+            return color, True
+    flattened = color.reshape(-1)
+    if flattened.size == num_points:
+        return flattened, False
+    if flattened.size == num_points * 3:
+        return flattened.reshape((num_points, 3)), True
+    raise ValueError("Color array size does not match number of points.")
+
+
+def _make_plot_element(mesh, **kwargs) -> dict:
+    return {"mesh": mesh, "kwargs": kwargs}
+
+
+def _flatten_plotting_elements(elements: list) -> list:
+    """Recursively flatten nested lists of plotting elements."""
+    flattened = []
+    for item in elements:
+        if isinstance(item, list):
+            flattened.extend(_flatten_plotting_elements(item))
+        else:
+            flattened.append(item)
+    return flattened
+
+
+def show_plot(plotting_elements:list, title:str,  axes:bool=True, view_up:str="z", interactive:bool=True, camera:dict={}, screenshot:str=""):
+    '''
+    Shows the plot.
+
+    Parameters
+    -----------
+    plotting_elements : list
+        The list of PyVista plotting elements to plot.
+    title : str
+        The title of the plot.
+    axes : bool = True
+        A boolean on whether to show the axes or not.
+    viewup : str = "z"
+        The direction of the view up.
+    interactive : bool = True
+        A boolean on whether the plot is interactive or not.
+    '''
+    plotter = pv.Plotter()
+    if axes:
+        plotter.show_axes()
+
+    # Flatten nested lists to handle cases where users pass [plot_points_result]
+    plotting_elements = _flatten_plotting_elements(plotting_elements)
+
+    for element in plotting_elements:
+        if isinstance(element, dict) and "mesh" in element:
+            mesh = element["mesh"]
+            kwargs = element.get("kwargs", {})
+            plotter.add_mesh(mesh, **kwargs)
+        elif isinstance(element, tuple) and len(element) == 2:
+            mesh, kwargs = element
+            plotter.add_mesh(mesh, **kwargs)
+        elif isinstance(element, pv.Actor):
+            plotter.add_actor(element)
+        elif isinstance(element, pv.DataSet):
+            plotter.add_mesh(element)
+
+    if view_up:
+        view_map = {"x": (1, 0, 0), "y": (0, 1, 0), "z": (0, 0, 1)}
+        if isinstance(view_up, str):
+            view_up = view_map.get(view_up)
+        if view_up is not None:
+            plotter.camera.SetViewUp(*view_up)
+
+    if camera:
+        camera_obj = plotter.camera
+        if "position" in camera:
+            camera_obj.position = camera["position"]
+        if "focal_point" in camera:
+            camera_obj.focal_point = camera["focal_point"]
+        if "viewup" in camera:
+            viewup = camera["viewup"]
+            if isinstance(viewup, str):
+                viewup = {"x": (1, 0, 0), "y": (0, 1, 0), "z": (0, 0, 1)}.get(viewup)
+            if viewup is not None:
+                camera_obj.SetViewUp(*viewup)
+        if "distance" in camera:
+            camera_obj.distance = camera["distance"]
+
+    if screenshot:
+        plotter.show(title=title, interactive=interactive, screenshot=screenshot)
+    else:
+        plotter.show(title=title, interactive=interactive)
+
+
+def plot_points(points:np.ndarray, opacity:float=1., color:Union[str, np.ndarray]='#00629B', color_map:str='jet', size=6.,
+                additional_plotting_elements:list=[], show:bool=True):
+    '''
+    Plots a point cloud.
+
+    Parameters
+    -----------
+    points : np.ndarray
+        The points to plot.
+    opactity : float = 1.
+        The opacity of the plot. 0 is fully transparent and 1 is fully opaque.
+    color : str | np.ndarray = '#00629B'
+        The 6 digit color code to plot the points as. A numpy array of colors can be provided to color the points individually according to a cmap.
+    color_map : str = 'jet'
+        The color map to use if the color is a numpy array.
+    size : float = 6.
+        The size (radius) of the points.
+    additional_plotting_elemets : list = []
+        PyVista plotting elements that may have been returned from previous plotting functions that should be plotted with this plot.
+    show : bool = True
+        A boolean on whether to show the plot or not. If the plot is not shown, the plotting element is still returned.
+    '''
+    plotting_elements = _flatten_plotting_elements(additional_plotting_elements.copy())
+
+    original_dim = points.shape[-1]
+    original_dim = points.shape[-1]
+    points = _normalize_points(points)
+    plotting_points = pv.PolyData(points)
+    kwargs = dict(opacity=opacity, point_size=size, render_points_as_spheres=True)
+    if isinstance(color, str):
+        kwargs["color"] = color
+    elif isinstance(color, np.ndarray):
+        scalars, rgb = _extract_scalars(color, points.shape[0])
+        kwargs["scalars"] = scalars
+        kwargs["cmap"] = color_map
+        kwargs["rgb"] = rgb
+
+    plotting_elements.append(_make_plot_element(plotting_points, **kwargs))
+
+    if points.shape[-1] == 3:
+        view_up = "z"
+    else:
+        view_up = "y"
+
+    if show:
+        view_up = "z" if original_dim == 3 else "y"
+        show_plot(plotting_elements, 'Points', axes=1, view_up=view_up, interactive=True)
+    return plotting_elements
+
+
+
+def plot_curve(points:np.ndarray, opacity:float=1., color:Union[str, np.ndarray]='#00629B', color_map:str='jet', line_width:float=3.,
+              additional_plotting_elements:list=[], show:bool=True):
+    '''
+    Plots the B-spline Surface.
+
+    Parameters
+    -----------
+    points : np.ndarray -- shape=(num_points, num_physical_dimensions)
+        The points of the curve to be plotted.
+    opactity : float
+        The opacity of the plot. 0 is fully transparent and 1 is fully opaque.
+    color : str = '#00629B'
+        The 6 digit color code to plot the curve as. A numpy array of colors can be provided to color the points individually according to a cmap.
+    color_map : str = 'jet
+        The color map to use if the color is a numpy array.
+    additional_plotting_elemets : list
+        PyVista plotting elements that may have been returned from previous plotting functions that should be plotted with this plot.
+    show : bool
+        A boolean on whether to show the plot or not. If the plot is not shown, the plotting element is returned.
+    '''
+    # NOTE: The function object performs the evaluation(s) to get the points (and colors if applicable) and then these functions do the plotting.
+    
+    plotting_elements = _flatten_plotting_elements(additional_plotting_elements.copy())
+
+    points = _normalize_points(points)
+    plotting_line = pv.lines_from_points(points, close=False)
+    kwargs = dict(opacity=opacity, line_width=line_width, render_lines_as_tubes=True)
+    
+    
+    if isinstance(color, str):
+        kwargs["color"] = color
+    elif isinstance(color, np.ndarray):
+        scalars, rgb = _extract_scalars(color, points.shape[0])
+        kwargs["scalars"] = scalars
+        kwargs["cmap"] = color_map
+        kwargs["rgb"] = rgb
+
+    plotting_elements.append(_make_plot_element(plotting_line, **kwargs))
+
+    if show:
+        if original_dim < 3:
+            view_up = "y"
+        else:
+            view_up = "z"
+        # plotter.show(plotting_elements, f'B-spline Curve', axes=1, view_up=view_up, interactive=True)
+        show_plot(plotting_elements, 'Curve', axes=1, view_up=view_up, interactive=True)
+        return plotting_elements
+        
+    return plotting_elements
+
+
+def plot_surface(points:np.ndarray, plot_types:list=['function'], opacity:float=1., 
+                 color:Union[str, np.ndarray]='#00629B', color_map:str='jet', surface_texture:str="", 
+                 line_width:float=3., additional_plotting_elements:list=[], show:bool=True):
+    '''
+    Plots the B-spline Surface.
+
+    Parameters
+    -----------
+    points : np.ndarray -- shape=(num_points_u, num_points_v, num_physical_dimensions)
+        The type of points to be plotted. {evaluated_points, coefficients}
+    plot_types : list
+        The type of plot {function, wireframe}
+    opactity : float
+        The opacity of the plot. 0 is fully transparent and 1 is fully opaque.
+    color : str = '#00629B'
+        The 6 digit color code to plot the surface as. A numpy array of colors can be provided to color the points individually according to a cmap.
+    color_map : str = 'jet'
+        The color map to use if the color is a numpy array.
+    surface_texture : str = "" {"metallic", "glossy", ...}, optional
+        The surface texture to determine how light bounces off the surface.
+        This is kept for API compatibility.
+    additional_plotting_elemets : list
+        PyVista plotting elements that may have been returned from previous plotting functions that should be plotted with this plot.
+    show : bool
+        A boolean on whether to show the plot or not. If the plot is not shown, the plotting element is returned.
+    '''
+    plotting_elements = _flatten_plotting_elements(additional_plotting_elements.copy())
+
+    num_plot_u = points.shape[0]
+    num_plot_v = points.shape[1]
+    original_dim = points.shape[-1]
+
+    import csdl_alpha as csdl
+    if isinstance(points, csdl.Variable):
+        points = points.value
+
+    points = _normalize_grid(points)
+    x = points[:, :, 0]
+    y = points[:, :, 1]
+    z = points[:, :, 2]
+    mesh = pv.StructuredGrid(x, y, z)
+
+    num_points = num_plot_u * num_plot_v
+    scalar_kwargs = {}
+    if isinstance(color, np.ndarray):
+        color_values = color
+        if color_values.shape[:2] == (num_plot_u, num_plot_v):
+            color_values = color_values.reshape((num_points, -1)) if color_values.ndim > 2 else color_values.reshape(-1)
+        scalars, rgb = _extract_scalars(color_values, num_points)
+        scalar_kwargs = {"scalars": scalars, "cmap": color_map, "rgb": rgb}
+
+    if 'function' in plot_types:
+        kwargs = dict(opacity=opacity)
+        if isinstance(color, str):
+            kwargs["color"] = color
+        else:
+            kwargs.update(scalar_kwargs)
+        plotting_elements.append(_make_plot_element(mesh, **kwargs))
+    if 'wireframe' in plot_types:
+        kwargs = dict(opacity=opacity, style="wireframe", line_width=line_width)
+        if isinstance(color, str):
+            kwargs["color"] = color
+        else:
+            kwargs.update(scalar_kwargs)
+        plotting_elements.append(_make_plot_element(mesh, **kwargs))
+
+    if show:
+        if original_dim < 3:
+            view_up = "y"
+        else:
+            view_up = "z"
+        show_plot(plotting_elements, 'Surface', axes=1, view_up=view_up, interactive=True)
+
+    return plotting_elements
+
+def get_surface_mesh(surface, color=None, grid_n=50, offset=0):
+    import lsdo_function_spaces as fs
+    surface:fs.Function = surface
+
+    # Generate meshgrid of parametric coordinates
+    mesh_grid_input = []
+    for dimension_index in range(2):
+        mesh_grid_input.append(np.linspace(0., 1., grid_n))
+    parametric_coordinates_tuple = np.meshgrid(*mesh_grid_input, indexing='ij')
+    for dimensions_index in range(2):
+        parametric_coordinates_tuple[dimensions_index] = parametric_coordinates_tuple[dimensions_index].reshape((-1,1))
+    grid = np.hstack(parametric_coordinates_tuple)
+
+    # grid = surface.space.generate_parametric_grid(grid_n)
+    points = surface.evaluate(grid, non_csdl=True).reshape((grid_n, grid_n, surface.num_physical_dimensions))
+    vertices = []
+    faces = []
+    for u_index in range(grid_n):
+        for v_index in range(grid_n):
+            vertex = tuple(points[u_index, v_index, :])
+            vertices.append(vertex)
+            if u_index != 0 and v_index != 0:
+                face = tuple((
+                    (u_index-1)*grid_n+(v_index-1)+offset,
+                    (u_index-1)*grid_n+(v_index)+offset,
+                    (u_index)*grid_n+(v_index)+offset,
+                    (u_index)*grid_n+(v_index-1)+offset,
+                ))
+                faces.append(face)
+    if color is not None:
+        c_points = color.evaluate(grid, non_csdl=True)
+        if len(c_points.shape) > 1:
+            if c_points.shape[1] > 1:
+                c_points = np.linalg.norm(c_points, axis=1)
+        return vertices, faces, c_points
+    return vertices, faces
+
+
+def make_scalar_bar_element(color_min: float, color_max: float, color_map: str = "jet"):
+    points = np.array([[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]])
+    mesh = pv.PolyData(points)
+    scalars = np.array([color_min, color_max])
+    kwargs = dict(scalars=scalars, cmap=color_map, show_scalar_bar=True, opacity=0.0)
+    return _make_plot_element(mesh, **kwargs)
+

lsdo_function_spaces/utils/utility_functions.py

@@ -0,0 +1,148 @@
+import numpy as np
+import numpy.typing as npt
+from typing import Optional
+import lsdo_function_spaces as lfs
+
+def create_b_spline_from_corners(corners:npt.NDArray[np.float64], degree:tuple[int,...]=(3,), num_coefficients:tuple[int,...]=(10,), knot_vectors:Optional[tuple[npt.NDArray[np.float64]]]=None,
+                                 name:str='b_spline_hyper_volume') -> lfs.Function:
+    '''
+    Creates a B-Spline volume from a set of corners.
+
+    Parameters
+    ----------
+    corners : np.ndarray
+        The corners of the hyper-volume. The shape of the corners array should be (nu1, nu2, nu3, ..., num_physical_dimensions) 
+        where u_{i} corresponds to number of corners along a parametric dimensions.
+    degree : tuple
+        The degree of the B-Spline in each dimension.
+    num_coefficients : tuple
+        The number of coefficients between each corner in each dimension.
+    knot_vectors : tuple
+        The knot vectors for each dimension. If None, then open uniform knot vectors are generated.
+    name : str = 'b_spline_hyper_volume'
+        The name of the B-Spline.
+
+    Returns
+    -------
+    b_spline : lfs.Function
+        The B-Spline hyper-volume.
+    '''
+
+    num_dimensions = len(corners.shape)-1
+    
+    if isinstance(degree, int):
+        degree = (degree,)*num_dimensions
+    if len(degree) != num_dimensions:
+        degree = tuple(np.tile(degree, num_dimensions))
+    if isinstance(num_coefficients, int):
+        num_coefficients = (num_coefficients,)*num_dimensions
+    if len(num_coefficients) != num_dimensions:
+        num_coefficients = tuple(np.tile(num_coefficients, num_dimensions))
+    if knot_vectors is not None:
+        if len(knot_vectors) != num_dimensions:
+            knot_vectors = tuple(np.tile(knot_vectors, num_dimensions))
+
+        total_knot_vector = []
+        for knot_vector in knot_vectors:
+            total_knot_vector.append(knot_vector)
+        knot_vectors = np.hstack(total_knot_vector)
+    else:
+        knot_vectors = None # Just let the B-spline space generate the knot vectors.
+
+    # Build up hyper-volume based on corners given
+    previous_dimension_hyper_volume = corners
+    dimension_hyper_volumes = corners.copy()
+    for dimension_index in np.arange(num_dimensions, 0, -1)-1:
+        dimension_hyper_volumes_shape = np.array(previous_dimension_hyper_volume.shape)
+        dimension_num_hyper_volumes = dimension_hyper_volumes_shape[dimension_index]-1
+        dimension_hyper_volumes_shape[dimension_index] = dimension_num_hyper_volumes * (num_coefficients[dimension_index]-1) + 1
+        dimension_hyper_volumes_shape = tuple(dimension_hyper_volumes_shape)
+        dimension_hyper_volumes = np.zeros(dimension_hyper_volumes_shape)
+
+        # Move dimension index to front so we can index the correct dimension
+        linspace_index_front = np.moveaxis(dimension_hyper_volumes, dimension_index, 0)
+        previous_index_front = np.moveaxis(previous_dimension_hyper_volume, dimension_index, 0)
+        include_endpoint = False
+        # Perform interpolations
+        for dimension_level_index in range(previous_dimension_hyper_volume.shape[dimension_index]-1):
+            if dimension_level_index == previous_dimension_hyper_volume.shape[dimension_index]-2:   # last hyper-volume/segment along dimension
+                include_endpoint = True
+                dimension_hyper_volume_num_sections = num_coefficients[dimension_index]
+                linspace_index_front[dimension_level_index*(dimension_hyper_volume_num_sections-1):] = \
+                        np.linspace(previous_index_front[dimension_level_index], previous_index_front[dimension_level_index+1],
+                                dimension_hyper_volume_num_sections, endpoint=include_endpoint)
+                continue
+
+            dimension_hyper_volume_num_sections = num_coefficients[dimension_index] - 1
+            linspace_index_front[dimension_level_index*dimension_hyper_volume_num_sections:
+                                 (dimension_level_index+1)*dimension_hyper_volume_num_sections] = \
+                    np.linspace(previous_index_front[dimension_level_index], previous_index_front[dimension_level_index+1],
+                            dimension_hyper_volume_num_sections, endpoint=include_endpoint)
+        # Move axis back to proper location
+        dimension_hyper_volumes = np.moveaxis(linspace_index_front, 0, dimension_index)
+        previous_dimension_hyper_volume = dimension_hyper_volumes.copy()
+
+    b_spline_space = lfs.BSplineSpace(num_parametric_dimensions=num_dimensions, degree=degree, 
+                                  coefficients_shape=dimension_hyper_volumes.shape[:-1], knots=knot_vectors)
+    b_spline = lfs.Function(space=b_spline_space, coefficients=dimension_hyper_volumes, name=name)
+
+    return b_spline
+
+
+def create_enclosure_block(points:np.ndarray, num_coefficients:tuple[int], degree:tuple[int], knot_vectors:tuple=None, 
+                                      num_parametric_dimensions:int=3, name:str='hyper_volume') -> lfs.Function:
+    '''
+    Creates an nd volume that tightly fits around a set of entities.
+
+    Parameters
+    ----------
+    points: np.ndarray
+        The points that the hyper-volume should enclose. The shape of the points array should be (num_points, num_physical_dimensions).
+    num_coefficients: tuple[int]
+        The number of coefficients in each dimension.
+    degree: tuple[int]
+        The degree of the B-Spline in each dimension.
+    knot_vectors: tuple = None
+        The knot vectors for each dimension. If None, then open uniform knot vectors are generated.
+    num_parametric_dimensions: int = 3
+        The number of parametric dimensions.
+    name: str = 'hyper_volume'
+        The name of the hyper-volume.
+
+    Returns
+    -------
+    hyper_volume: lfs.Function
+        The hyper-volume that encloses the points.
+    '''
+    if isinstance(num_coefficients, int):
+        num_coefficients = (num_coefficients,)*num_parametric_dimensions
+    if isinstance(degree, int):
+        degree = (degree,)*num_parametric_dimensions
+
+    num_physical_dimensions = points.shape[-1]
+
+    mins = np.min(points.reshape((-1,num_physical_dimensions)), axis=0).reshape((-1,1))
+    maxs = np.max(points.reshape((-1,num_physical_dimensions)), axis=0).reshape((-1,1))
+
+    mins_and_maxs = np.hstack((mins, maxs))
+
+    corners_shape = (2,)*num_parametric_dimensions + (num_physical_dimensions,)
+    corners = np.zeros(corners_shape)
+    corners_flattened = np.zeros((np.prod(corners_shape),))
+    physical_dimension_index = 0
+    for i in range(len(corners_flattened)):
+        parametric_dimension_counter = int(i/num_physical_dimensions)
+        binary_parametric_dimension_counter = bin(parametric_dimension_counter)[2:].zfill(num_physical_dimensions)
+        min_or_max = int(binary_parametric_dimension_counter[physical_dimension_index])
+        corners_flattened[i] = mins_and_maxs[physical_dimension_index, min_or_max]
+
+        physical_dimension_index += 1
+        if physical_dimension_index == num_physical_dimensions:
+            physical_dimension_index = 0
+
+    corners = corners_flattened.reshape(corners_shape)
+
+    hyper_volume = create_b_spline_from_corners(name=name, corners=corners, degree=degree, num_coefficients=num_coefficients,
+            knot_vectors=knot_vectors)
+
+    return hyper_volume

lsdo_function_spaces-1.0.0.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: lsdo_function_spaces
+Version: 1.0.0
+Summary: A package for functional representation and function spaces in multidisciplinary design optimization.
+Author-email: Andrew Fletcher <afletcher168@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Documentation, https://lsdo-function-spaces.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/LSDOlab/lsdo_function_spaces
+Project-URL: Issue Tracker, https://github.com/LSDOlab/lsdo_function_spaces/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pyvista
+Requires-Dist: joblib
+Requires-Dist: pandas
+Requires-Dist: scikit-learn
+Requires-Dist: jax
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: docs
+Requires-Dist: myst-nb; extra == "docs"
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-autoapi>=3.0; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: gitpython; extra == "docs"
+Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
+Dynamic: license-file
+
+# lsdo_function_spaces
+
+[![Documentation Status](https://readthedocs.org/projects/lsdo-function-spaces/badge/?version=latest)](https://lsdo-function-spaces.readthedocs.io/en/latest/?badge=latest)
+[![Tests](https://github.com/LSDOlab/lsdo_function_spaces/actions/workflows/actions.yml/badge.svg)](https://github.com/LSDOlab/lsdo_function_spaces/actions)
+![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)
+[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](LICENSE.txt)
+
+**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.
+
+Developed by the [Large-Scale Design Optimization (LSDO) Lab](https://lsdo.eng.ucsd.edu/) 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
+
+| Subpackage | Key Classes / Functions | Description |
+|:---|:---|:---|
+| **`lsdo_function_spaces.core.spaces`** | `BSplineSpace`, `FunctionSpace`, `ShepardSpace`, `PolynomialSpace`, `RBFSpace` | Core function space representations, basis function evaluations, and tensor-product constructions. |
+| **`lsdo_function_spaces.core.function`** | `Function`, `FunctionSet` | Concrete functional instances binding coefficient vectors to function spaces, supporting evaluation and composition. |
+| **`lsdo_function_spaces.core.spaces.non_cython_bsplines`** | `project_points_gauss_newton_numpy`, `project_points_lm_numpy`, `LMParams` | Vectorized inverse point projection engines utilizing active-set Levenberg-Marquardt and Gauss-Newton solvers. |
+| **`lsdo_function_spaces.core.b_spline_csdl_custom_ops`** | Custom CSDL evaluation operations | Differentiable computational graph operations providing exact forward and reverse-mode derivative evaluations. |
+
+---
+
+## Quickstart
+
+### Creating and Evaluating a B-spline Surface
+
+```python
+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
+
+```python
+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:
+
+```sh
+# 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:
+```sh
+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:
+```sh
+pytest -v tests/ --cov=lsdo_function_spaces --cov-report=term-missing
+```
+
+For environments without a physical display (e.g. CI runners), run with `xvfb`:
+```sh
+xvfb-run --auto-servernum pytest -v tests/
+```
+
+---
+
+## Documentation
+
+Build the HTML documentation locally:
+```sh
+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](LICENSE.txt)).