yapss 0.1.0__tar.gz

yapss-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.tox/
+
+/env*/
+/dist/
+venv*/
+.jupyter/
+.ipynb*/
+generated/
+
+__pycache__/
+
+/docs/build/
+/docs/user_guide/build/
+/docs/user_guide/notebooks/*.ipynb
+/docs/user_guide/scripts/plots/*.png
+/docs/user_guide/scripts/plots/*.txt
+/docs/user_guide/CHANGELOG.md
+/docs/user_guide/CONTRIBUTING.md

yapss-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project
+adheres to [PyPA versioning
+guidelines](https://packaging.python.org/en/latest/specifications/version-specifiers/).
+YAPSS is currently in initial development (0.x), and hence the public API should not be
+considered stable. YAPSS will follow a predictable versioning policy during 0.x development:
+
+- Breaking changes or major new features may occur at minor version changes (e.g., from 
+  0.3.x to 0.4.0).
+- Patch releases (e.g., 0.3.1, 0.3.2) within the same minor version are backwards-compatible
+  and will not introduce breaking changes.
+- Users can pin to a specific minor version (e.g., yapss>=0.3.0,<0.4.0) to avoid unexpected 
+  changes, but should expect significant updates when upgrading to a new minor version.
+
+<!-- 
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+-->
+
+---
+
+## 0.1.0 - 2024-12-28
+
+### Added
+
+Initial release of the software package. Features include:
+
+- Computational approach based on the GPOPS-II algorithm of Patterson and Rao (2014). 
+- Support for multiple differentiation methods: automatic differentiation via the CasADi package,
+  user-defined derivatives, and central difference numerical differentiation for problems not
+  amenable to automatic differentiation.
+- Choice of collocation method, including Legendre-Gauss (LG), Legendre-Gauss-Radau (LGR),
+  and Legendre-Gauss-Lobatto (LGL) options.
+- Segmented mesh support, enabling mesh refinement in specific regions. (Automatic mesh refinement is
+  not yet available.)
+- An API for defining optimal control problems designed to catch common errors and
+  provide helpful messages.
+- Documentation covering installation, setup, and example usage.
+- Examples available as both Python scripts and Jupyter notebooks.
+- Nearly complete test coverage for all modules.

yapss-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2024 Massachusetts Institute of Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yapss-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: yapss
+Version: 0.1.0
+Summary: A Python package for solving optimal control problems using pseudospectral methods.
+Project-URL: Documentation, https://yapss.readthedocs.io/
+Project-URL: Repository, https://github.com/stevenrhall/yapss.git
+Project-URL: Issues, https://github.com/stevenrhall/yapss/issues
+Project-URL: Changelog, https://github.com/stevenrhall/yapss/blob/main/CHANGELOG.md
+Author-email: "Steven R. Hall" <steve@steven-hall.net>
+Maintainer-email: "Steven R. Hall" <steve@steven-hall.net>
+License-File: LICENSE
+Keywords: optimal control,optimization,pseudospectral methods
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: casadi>=3.6.0
+Requires-Dist: matplotlib
+Requires-Dist: mpmath
+Requires-Dist: mseipopt
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: dev
+Requires-Dist: black[jupyter]<25.0.0,>=24.0.0; extra == 'dev'
+Requires-Dist: furo; extra == 'dev'
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: isort; extra == 'dev'
+Requires-Dist: jupyterlab; extra == 'dev'
+Requires-Dist: jupyterlab-code-formatter; extra == 'dev'
+Requires-Dist: jupyterlab-spellchecker; extra == 'dev'
+Requires-Dist: lxml; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: myst-parser; extra == 'dev'
+Requires-Dist: nbsphinx; extra == 'dev'
+Requires-Dist: nbwipers; extra == 'dev'
+Requires-Dist: numpydoc; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: sphinx; extra == 'dev'
+Requires-Dist: sphinx-copybutton; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme; extra == 'dev'
+Requires-Dist: sphinxcontrib-bibtex; extra == 'dev'
+Requires-Dist: tox; extra == 'dev'
+Provides-Extra: doc
+Requires-Dist: furo; extra == 'doc'
+Requires-Dist: jupyterlab; extra == 'doc'
+Requires-Dist: myst-parser; extra == 'doc'
+Requires-Dist: nbsphinx; extra == 'doc'
+Requires-Dist: numpydoc; extra == 'doc'
+Requires-Dist: sphinx; extra == 'doc'
+Requires-Dist: sphinx-copybutton; extra == 'doc'
+Requires-Dist: sphinx-rtd-theme; extra == 'doc'
+Requires-Dist: sphinxcontrib-bibtex; extra == 'doc'
+Provides-Extra: notebook
+Requires-Dist: black[jupyter]<25.0.0,>=24.0.0; extra == 'notebook'
+Requires-Dist: ipython; extra == 'notebook'
+Requires-Dist: isort; extra == 'notebook'
+Requires-Dist: jupyterlab; extra == 'notebook'
+Requires-Dist: jupyterlab-code-formatter; extra == 'notebook'
+Requires-Dist: jupyterlab-spellchecker; extra == 'notebook'
+Description-Content-Type: text/markdown
+
+# YAPSS: Yet Another Pseudo-Spectral Solver
+
+YAPSS is a Python package for numerically solving optimal control problems using
+pseudospectral methods. Features include:
+
+- Computational approach based on the GPOPS-II algorithm of
+  [Patterson and Rao (2014)](https://dl.acm.org/doi/pdf/10.1145/2558904)
+- Support for multiple differentiation methods: automatic differentiation via the CasADi
+  package, user-defined derivatives, and central difference numerical differentiation for
+  problems not amenable to automatic differentiation.
+- Choice of collocation method, including Legendre-Gauss (LG), Legendre-Gauss-Radau (LGR),
+  and Legendre-Gauss-Lobatto (LGL) options.
+- Segmented mesh support, enabling mesh refinement in specific regions. (Automatic mesh
+  refinement is not yet available.)
+- An API for defining optimal control problems designed to catch common errors
+  and provide helpful messages.
+- Documentation covering installation, setup, and example usage.
+- Examples available as both Python scripts and Jupyter notebooks.
+
+## Quickstart
+
+To get started, install YAPSS  and verify the installation using pip:
+
+```console
+$ python -m venv yapss-env
+$ source yapss-env/bin/activate
+(yapss-env) $ pip install yapss
+(yapss-env) $ python -m yapss.examples.isoperimetric
+```
+
+If the console output shows a small relative error and a Matplotlib window displays 
+a circle, the installation is successful!
+
+For more detailed installation instructions, see the next section.
+
+## Installation
+
+YAPSS supports installation via Conda or pip. It requires Python 3.9 or later..
+
+### Option 1: Using Conda
+
+Create and activate a virtual environment, and install YAPSS:
+
+```console
+$ conda create -n yapss-env python=3.9
+$ conda activate yapss-env
+(yapss-env) $ conda install -c conda-forge yapss
+```
+
+If you encounter the following error during installation
+
+```text
+PackagesNotFoundError: The following packages are not available from current channels:
+  - yapss
+```
+
+then YAPSS is not yet available on conda-forge. In this case, install from source as follows:
+
+```console
+(yapss-env) $ conda install -c conda-forge numpy casadi scipy mpmath matplotlib cyipopt -y
+(yapss-env) $ pip install git+https://github.com/stevenrhall/yapss.git@v0.1.0 --no-deps
+```
+
+The ``--no-deps`` flag is important — it prevents pip from reinstalling dependencies that
+Conda has already installed, avoiding conflicts. You can delete the tag ``@v0.1.0`` to
+install the latest version, or specify a different version tag.
+
+### Option 2: Using Pip
+
+Create and activate a virtual environment, then install YAPSS:
+
+```console
+$ python -m venv yapss-env
+$ source yapss-env/bin/activate
+(yapss-env) $ pip install yapss
+```
+
+To install from source:
+
+```console
+(yapss-env) $ pip install git+https://github.com/stevenrhall/yapss.git@v0.1.0
+```
+
+### Verify the Installation
+
+To verify the installation, run the isoperimetric example:
+
+```console
+(yapss-env) $ python -m yapss.examples.isoperimetric
+```
+
+The result should be a matplotlib window with a plot of the optimal curve (a circle), and
+console output that concludes with something similar to
+
+```text
+Maximum area = 0.07957747154594766 (Should be 1 / (4 pi) = 0.07957747154594767)
+Relative error in solution = 1.743934249004316e-16
+```
+
+If the plot does not display, add `%matplotlib inline` in a Jupyter notebook or set the 
+backend with `matplotlib.use('Agg')` for headless environments.
+
+The console output may differ slightly depending on machine precision. Minor deviations in
+the final digits are normal, and the relative error should be on the order of machine
+precision. If it is, the installation is correct.
+
+Additional examples are available in 
+
+- the examples/notebooks directory
+- the src/yapss/examples directory
+- the Examples section of the documentation.
+
+## License
+
+YAPSS is licensed under the MIT License. See the LICENSE file for more information.
+
+## Documentation
+
+The [documentation](https://yapss.readthedocs.io/) is available on Read the Docs.
+
+## Contributing
+
+YAPSS is open source — contributions are not only welcome but encouraged. See
+[CONTRIBUTING.md](https://github.com/stevenrhall/yapss/blob/main/CONTRIBUTING.md) for details.
+

yapss-0.1.0/README.md

@@ -0,0 +1,125 @@
+# YAPSS: Yet Another Pseudo-Spectral Solver
+
+YAPSS is a Python package for numerically solving optimal control problems using
+pseudospectral methods. Features include:
+
+- Computational approach based on the GPOPS-II algorithm of
+  [Patterson and Rao (2014)](https://dl.acm.org/doi/pdf/10.1145/2558904)
+- Support for multiple differentiation methods: automatic differentiation via the CasADi
+  package, user-defined derivatives, and central difference numerical differentiation for
+  problems not amenable to automatic differentiation.
+- Choice of collocation method, including Legendre-Gauss (LG), Legendre-Gauss-Radau (LGR),
+  and Legendre-Gauss-Lobatto (LGL) options.
+- Segmented mesh support, enabling mesh refinement in specific regions. (Automatic mesh
+  refinement is not yet available.)
+- An API for defining optimal control problems designed to catch common errors
+  and provide helpful messages.
+- Documentation covering installation, setup, and example usage.
+- Examples available as both Python scripts and Jupyter notebooks.
+
+## Quickstart
+
+To get started, install YAPSS  and verify the installation using pip:
+
+```console
+$ python -m venv yapss-env
+$ source yapss-env/bin/activate
+(yapss-env) $ pip install yapss
+(yapss-env) $ python -m yapss.examples.isoperimetric
+```
+
+If the console output shows a small relative error and a Matplotlib window displays 
+a circle, the installation is successful!
+
+For more detailed installation instructions, see the next section.
+
+## Installation
+
+YAPSS supports installation via Conda or pip. It requires Python 3.9 or later..
+
+### Option 1: Using Conda
+
+Create and activate a virtual environment, and install YAPSS:
+
+```console
+$ conda create -n yapss-env python=3.9
+$ conda activate yapss-env
+(yapss-env) $ conda install -c conda-forge yapss
+```
+
+If you encounter the following error during installation
+
+```text
+PackagesNotFoundError: The following packages are not available from current channels:
+  - yapss
+```
+
+then YAPSS is not yet available on conda-forge. In this case, install from source as follows:
+
+```console
+(yapss-env) $ conda install -c conda-forge numpy casadi scipy mpmath matplotlib cyipopt -y
+(yapss-env) $ pip install git+https://github.com/stevenrhall/yapss.git@v0.1.0 --no-deps
+```
+
+The ``--no-deps`` flag is important — it prevents pip from reinstalling dependencies that
+Conda has already installed, avoiding conflicts. You can delete the tag ``@v0.1.0`` to
+install the latest version, or specify a different version tag.
+
+### Option 2: Using Pip
+
+Create and activate a virtual environment, then install YAPSS:
+
+```console
+$ python -m venv yapss-env
+$ source yapss-env/bin/activate
+(yapss-env) $ pip install yapss
+```
+
+To install from source:
+
+```console
+(yapss-env) $ pip install git+https://github.com/stevenrhall/yapss.git@v0.1.0
+```
+
+### Verify the Installation
+
+To verify the installation, run the isoperimetric example:
+
+```console
+(yapss-env) $ python -m yapss.examples.isoperimetric
+```
+
+The result should be a matplotlib window with a plot of the optimal curve (a circle), and
+console output that concludes with something similar to
+
+```text
+Maximum area = 0.07957747154594766 (Should be 1 / (4 pi) = 0.07957747154594767)
+Relative error in solution = 1.743934249004316e-16
+```
+
+If the plot does not display, add `%matplotlib inline` in a Jupyter notebook or set the 
+backend with `matplotlib.use('Agg')` for headless environments.
+
+The console output may differ slightly depending on machine precision. Minor deviations in
+the final digits are normal, and the relative error should be on the order of machine
+precision. If it is, the installation is correct.
+
+Additional examples are available in 
+
+- the examples/notebooks directory
+- the src/yapss/examples directory
+- the Examples section of the documentation.
+
+## License
+
+YAPSS is licensed under the MIT License. See the LICENSE file for more information.
+
+## Documentation
+
+The [documentation](https://yapss.readthedocs.io/) is available on Read the Docs.
+
+## Contributing
+
+YAPSS is open source — contributions are not only welcome but encouraged. See
+[CONTRIBUTING.md](https://github.com/stevenrhall/yapss/blob/main/CONTRIBUTING.md) for details.
+

yapss-0.1.0/examples/notebooks/Makefile

@@ -0,0 +1,17 @@
+.PHONY: help
+# adapted from https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+help: ## Print this help message.
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[35m%-20s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: execute
+execute: $(wildcard *.ipynb) ## Execute all JupyterLab notebooks in place
+	@for f in $(shell ls *.ipynb); do jupyter nbconvert --execute --inplace $${f}; done
+
+.PHONY: clean
+clean: $(wildcard *.ipynb) ## Clear output cells and remove kernel and language metadata from all JupyterLab notebooks
+	nbwipers clean-all . -y
+	@for nb in *.ipynb; do \
+		echo "Stripping kernel metadata from $$nb"; \
+		jq 'del(.metadata.kernelspec, .metadata.language_info)' "$$nb" > tmp_$$nb && mv tmp_$$nb "$$nb"; \
+	done
+	rm -rf .ipynb_checkpoints