Metadata-Version: 2.4
Name: SPOMSO
Version: 1.5.1
Summary: Python package for generating geometry and vector fields with SDFs, with GPU support and automatic differentiation.
Author-email: Peter Ropač <peter.ropac@fmf.uni-lj.si>
Maintainer-email: Peter Ropač <peter.ropac@fmf.uni-lj.si>
License-Expression: LGPL-3.0-or-later
Project-URL: Homepage, https://github.com/peterropac/Aegolius
Project-URL: Documentation, https://aegolius.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/peterropac/Aegolius
Project-URL: Issues, https://github.com/peterropac/Aegolius/issues
Project-URL: Changelog, https://github.com/peterropac/Aegolius/blob/main/CHANGELOG.md
Keywords: python,geometry,sdf,signed distance function,signed distance field,procedural geometry,level set,vector field,director field,computational geometry,jax,automatic differentiation,gpu,optimization,shape optimization,inverse design
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
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 :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: autodiff
Requires-Dist: jax; extra == "autodiff"
Requires-Dist: jaxlib; extra == "autodiff"
Requires-Dist: optax; extra == "autodiff"
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Requires-Dist: plotly; extra == "plot"
Provides-Extra: all
Requires-Dist: jax; extra == "all"
Requires-Dist: jaxlib; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: plotly; extra == "all"
Requires-Dist: optax; extra == "all"
Dynamic: license-file

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)"
            srcset="https://raw.githubusercontent.com/peterropac/Aegolius/main/files/Images/comb_230623_2.png">
    <img alt="SPOMSO: geometry and vector fields from signed distance functions"
         src="https://raw.githubusercontent.com/peterropac/Aegolius/main/files/Images/comb_220224_0.png"
         width="700">
  </picture>
</div>

**Aegolius** is the public repository for the Python package **SPOMSO**.

**SPOMSO** is free and open-source software distributed under the [GNU LGPL](https://www.gnu.org/licenses/lgpl-3.0.html). This package is designed for the procedural construction of geometry and vector fields based on [Signed Distance Functions](https://en.wikipedia.org/wiki/Signed_distance_function) (SDFs).

[![PyPI version](https://img.shields.io/pypi/v/spomso)](https://pypi.org/project/spomso/)
[![License](https://img.shields.io/github/license/peterropac/Aegolius)](https://github.com/peterropac/Aegolius/blob/main/LICENSE)
[![Docs](https://img.shields.io/readthedocs/aegolius)](https://aegolius.readthedocs.io/en/latest/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8090670.svg)](https://doi.org/10.5281/zenodo.8090670)
[![GitHub stars](https://img.shields.io/github/stars/peterropac/Aegolius)](https://github.com/peterropac/Aegolius/stargazers)

---

## Key Features - SDFs

-   Support for both **2D** and **3D** geometry.
-   Object-oriented and functional approaches to defining geometry with pre-defined 2D and 3D objects.
-   Built-in [Euclidean Transformations](https://en.wikipedia.org/wiki/Rigid_transformation) (translation, rotation, scaling).
-   Seamless conversion between point clouds and SDFs.
-   Over 50 built-in SDF modifications, including:
    *   Extrusion, revolution, twist, bend, and elongation.
    *   Mirroring, symmetry, and rotational symmetry.
    *   Finite and infinite instancing (along lines, segmented lines, and parametric curves).
    *   Surface-to-volume and volume-to-surface operations.
    *   Various post-processing functions 
    *   Custom user-defined modifications.
-   13 distinct methods for combining geometric objects, including different implementations of:
    *   Boolean operations (union, intersection, subtraction).
    *   Smooth operations (smooth union, smooth intersection, smooth subtraction).

## Key Features - Vector Fields

-   Support for **2D** and **3D** vector fields.
-   Object-oriented and functional approaches with pre-defined vector fields. 
-   Ability to define vector fields from scalar fields/SDFs or custom functions.
-   Extensive modifications and transformations, including:
    *   Addition, subtraction, and rescaling.
    *   Element-wise rotations in polar and azimuthal directions.
    *   Element-wise rotations around arbitrary axes.
    *   Revolutions of 2D vector fields around principal axes.

## Key Features - Automatic Differentiation

A [JAX](https://jax.readthedocs.io/en/latest/) implementation is available for nearly all SDFs, modifications, combinations, and post-processing functions. 
This enables computationally demanding operations to be offloaded to the GPU, with full support for [Automatic Differentiation](https://en.wikipedia.org/wiki/Automatic_differentiation).

**JAX** is an optional dependency and will not be installed by default.

---

## Examples

The repository contains a wide variety of use cases:
-   [2D Examples](https://github.com/peterropac/Aegolius/tree/main/examples/scalar/2D) (27 scripts) and [3D Examples](https://github.com/peterropac/Aegolius/tree/main/examples/scalar/3D) (17 scripts) demonstrating geometry construction.
-   [Vector Examples](https://github.com/peterropac/Aegolius/tree/main/examples/vector) (7 scripts) for vector field manipulation.
-   [Automatic Differentiation Examples](https://github.com/peterropac/Aegolius/tree/main/examples/autodiff) (8 scripts) showcasing JAX integration.

All examples are provided in both Python script (`.py`) and interactive Jupyter Notebook (`.ipynb`) formats.

There are also [LLM Examples](https://github.com/peterropac/Aegolius/tree/main/examples/LLM) demonstrating how to use various (open-source) LLMs to generate complex geometry.

---

## Installation

The simplest method to install SPOMSO is via `pip install spomso`.

For more information, please refer to `aegolius_install.ipynb` in the [Examples](https://github.com/peterropac/Aegolius/tree/main/examples) folder.

## Citing

If you use SPOMSO in your research, please cite the latest archived repository of Aegolius on Zenodo:

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8090670.svg)](https://doi.org/10.5281/zenodo.8090670)

## Documentation

Access the official [Documentation here](https://aegolius.readthedocs.io/en/latest/).

## Acknowledgements

This work was supported by the [Faculty of Mathematics and Physics at the University of Ljubljana](https://www.fmf.uni-lj.si/en/) and the [Institute Jožef Stefan](https://ijs.si/ijsw/V001/JSI). Special thanks to my colleagues for their helpful discussions.
