Homepage

.github/workflows/deploy.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: '3.11'
       - name: Install dependencies
         run: python -m pip install --upgrade -r requirements.txt -r docs/requirements.txt
       - name: Install Pycollo

.github/workflows/docs.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: '3.11'
       - name: Install dependencies
         run: python -m pip install --upgrade -r requirements.txt -r docs/requirements.txt
       - name: Install Pycollo

.github/workflows/lint.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-            python-version: '3.10'
+            python-version: '3.11'
       - name: Install dependencies
         run: python -m pip install --upgrade ruff
       - name: Lint with Ruff

.github/workflows/publish.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: '3.11'
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip

.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ['3.8', '3.9', '3.10']
+        python-version: ['3.8', '3.9', '3.10', '3.11']
     defaults:
       run:
         shell: bash -l {0}

README.rst

@@ -27,8 +27,8 @@ To install using pip, enter the following command at a command prompt:
 
 For more information, refer to the `installation documentation <https://pycollo.readthedocs.io/en/latest/user/installation.html>`_.
 
-Contribute
-==========
+Contributing
+============
 
 Pycollo is currently under development. Major code refactors, including significant API changes, are likely. As such contributions may not be readily accepted at this time. If you are keen to contribute, please contact the authors by email or file an issue on the issue tracker detailing how you would like to get involved.
 
@@ -45,6 +45,12 @@ Authors
 
 - Sam Brockie - sgb39@cam.ac.uk
 
+
+Acknowledgements
+================
+
+A special thanks is owed to Jan Heinen, Jason K. Moore, and the Chan Zuckerberg Initiative for their fantastic contributions to the Pycollo documentation.
+
 Citation
 ========
 

docs/conf.py

@@ -27,6 +27,7 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
+    "sphinxcontrib.bibtex",
 ]
 
 templates_path = ["_templates"]
@@ -45,6 +46,7 @@
     "python": ("http://docs.python.org/3", None),
 }
 
+bibtex_bibfiles = ["references.bib"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -56,3 +58,4 @@
 }
 
 html_static_path = ["_static"]
+

docs/contributing.rst

@@ -0,0 +1,24 @@
+============
+Contributing
+============
+
+Pycollo is currently under development. Major code refactors, including significant API changes, are likely. As such contributions may not be readily accepted at this time. If you are keen to contribute, please contact the authors by email or file an issue on the issue tracker detailing how you would like to get involved.
+
+Issue Tracker: https://github.com/brocksam/pycollo/issues
+
+Source Code: https://github.com/brocksam/pycollo
+
+License
+-------
+
+This project is licensed under the terms of the MIT license.
+
+Authors
+-------
+
+Sam Brockie - sambrockie@icloud.com
+
+Acknowledgements
+----------------
+
+Special thanks to Jan Heinen, Jason K. Moore, and the Chan Zuckerberg Initiative for their fantastic contributions to the Pycollo documentation.

docs/faq.rst

@@ -0,0 +1,8 @@
+==========================
+Frequently Asked Questions
+==========================
+
+Why is my code giving errors?
+-----------------------------
+
+Pycollo's error checking for bounds and guesses can give opaque error messages or even fail. Make sure that you have provided bounds and a guess for every variable and constraint where necessary. It can be helpful to look at the dimensions of all attributes and compare this to the bounds and guesses that you have supplied to ensure that these are equal. If they are not then you are probably missing some bounds or a guess.

docs/getting_started/background.rst

@@ -0,0 +1,61 @@
+================
+What is Pycollo?
+================
+
+Pycollo, a combination of Python and collocation, is a Python package for solving multiphase optimal control problems using direct orthogonal collocation.  
+
+In optimization there are shooting methods and simultaneous methods. A shooting method uses a simulation to enforce the system dynamics, while the collocation method enforces the dynamics at given points along the trajectory. Shooting methods are more prone to find a global solution, but are computationally heavy. Collocation methods tend to converge better and faster but are prone to find local minima. Direct methods are generally best for problems where dynamics and control must be computed to a similar accuracy, and the structure of the control trajectory is not known a priori :cite:p:`kelly_introduction_2017`.
+
+Pycollo is a direct orthogonal collocation transcription tool for Python :cite:p:`brockie_predictive_2021`. The dynamics and constraints are enforced over a discretization. The discretization exists of N collocation points. The collocation points are either mesh points or polynomial points, but all collocation points are enforced to the constraints and dynamics. After transcription the problem is passed to the solver IPOPT (Interior Point OPTimizer). When the found IPOPT solution does not meet the error-tolerance set in PyCollo, the discretization is refined and a new itera- tion is solved in IPOPT. Mesh points, polynomial points, mesh sections and mesh refinement are explained in figure 5. The polynomials are of the Legendre-Gauss-Lobatto (LGL) nature. More information on the mesh can be found in appendix A. The integration scheme is an implicit Runge-Kutta Kth method :cite:p:`brockie_predictive_2021`. This high order method will have a high accuracy with the disadvantage that all states and constraints need to be differentiable.
+
+It is highly advised to read :cite:p:`kelly_introduction_2017` if you are new to direct collocation.
+
+
+Multiphase direct collocation
+-----------------------------
+Some optimal control problems face discontinuities or changes in dynamics. Boolean operations can work in lower order optimization schemes, but with higher order schemes such as pycollo, every formulation needs to be differentiated. Differentiating of boolean operations is impossible or can lead to numerical instabillities (such as a sigmoid function). To still have the benefits of a higher order scheme and handle discontinuities one can use multiple continious phases. Each phase represents a distinct segment of the problem with its own set of dynamics, constraints, and control inputs. The main idea behind this scheme is to discretize each phase individually and then link the phases together by ensuring continuity of states and control inputs at phase boundaries. Between the phase boundaries discontinuities can be handeled such as impact, friction or change of dynamics. This approach allows you to tackle complex problems with changing dynamics or control strategies over different time intervals. 
+
+Pycollo will help you with the following steps:
+
+1. Discretization within Each Phase:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Within each phase, you discretize the continuous-time dynamics using collocation points. Collocation points are time instances within the phase where you will approximate the system dynamics using constraints. These points are often chosen based on established techniques like Gaussian quadrature.
+
+2. State and Control Parameterization:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For each phase, parameterize the state and control trajectories using LGL polynomial approximations.
+
+3. Dynamics and Constraint Approximation:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+At each collocation point within a phase, you approximate the system dynamics and constraints using discrete equations. This involves approximating the differential equations that describe the system's behavior and ensuring that path constraints and boundary conditions are met at these points.
+
+4. Endpoint Constraints:
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To ensure smooth transitions between phases, you enforce continuity constraints at the boundaries between phases. This involves linking the state and control variables from the final collocation point of one phase to the initial collocation point of the next phase. 
+
+5. Objective Function Discretization:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Discretize the objective function over each phase by approximating integrals as summations over the collocation points. This allows you to express the objective function in terms of the endpoint variables.
+
+6. Formulating the Optimization Problem:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With the discretized dynamics, constraints, and objective function in place for each phase, Pycollo formulates the complete optimization problem as a NLP. This program aims to find the optimal values of the discrete state and control variables across all phases, while satisfying the dynamics, constraints, and continuity conditions.
+
+7. Solving the Optimization Problem:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Pycollo uses IPOPT to solve the NLP
+
+8. Using a PH method to ensure tolerances are met:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pycollo adjusts the amount of collocation points (P) and size of the mesh sections (H), to ensure all tolerances are met. Whenever a state shows non linear behaviour the amount of collocation points in that section will increase to decrease errors. 
+
+In summary, a multiphase direct collocation scheme breaks down a complex optimal control problem into manageable phases, discretizes the dynamics and constraints within each phase, ensures continuity between phases, and solves the resulting optimization problem to find the optimal control strategy across multiple segments. This approach is particularly useful for problems where the system behavior and control strategies change over different time intervals.
+
+.. bibliography::

docs/getting_started/index.rst

@@ -0,0 +1,9 @@
+Getting Started
+===============
+
+.. toctree::
+    :maxdepth: 2
+    :titlesonly:
+
+    background
+    installation

docs/getting_started/installation.rst

@@ -0,0 +1,69 @@
+==========================
+Pycollo Installation Guide
+==========================
+
+Prerequisites
+=============
+
+Before you begin, ensure you have the following prerequisites installed:
+
+- Python (>= 3.8)
+
+Step 1: Create a Virtual Environment
+------------------------------------
+
+It is recommended to install Pycollo in a virtual environment to manage dependencies.
+
+1. Open a terminal or command prompt.
+
+2. Create a new virtual environment:
+
+   .. code-block:: bash
+
+      python -m venv pycollo-env
+
+3. Activate the virtual environment:
+
+   - On Windows:
+
+     .. code-block:: bash
+
+       .\pycollo-env\Scripts\activate
+
+   - On macOS and Linux:
+
+     .. code-block:: bash
+
+        source pycollo-env/bin/activate
+
+Step 2: Install Pycollo
+-----------------------
+
+To install with conda-forge enter the following command at a command prompt
+
+.. code-block:: bash
+
+    conda install -c conda-forge pycollo
+
+To install using conda, enter the following command at a command prompt:
+
+.. code-block:: bash
+
+    conda install pycollo
+
+To install using pip, enter the following command at a command prompt:
+
+.. code-block:: bash
+
+    pip install pycollo
+
+
+Pycollo and its dependencies will be downloaded and installed.
+
+.. note::
+
+   If you no longer need the virtual environment, you can deactivate it by running the command:
+
+   .. code-block:: bash
+
+      deactivate

docs/index.rst

@@ -1,10 +1,14 @@
-=====================
-Pycollo Documentation
-=====================
-Pycollo: an Open-Source Package for Multi Phase Direct Collocation.
+=======
+Pycollo
+=======
+
+General-purpose optimal control, trajectory optimisation and parameter optimisation using direct collocation.
 
 .. toctree::
     :maxdepth: 2
     :titlesonly:
 
+    getting_started/index
+    contributing
+    faq
     api_reference

docs/references.bib

@@ -0,0 +1,26 @@
+
+@article{kelly_introduction_2017,
+	title = {An {Introduction} to {Trajectory} {Optimization}:  {How} to {Do} {Your} {Own} {Direct} {Collocation}},
+	volume = {59},
+	issn = {0036-1445},
+	shorttitle = {An {Introduction} to {Trajectory} {Optimization}},
+	url = {https://epubs.siam.org/doi/10.1137/16M1062569},
+	doi = {10.1137/16M1062569},
+	abstract = {This paper is an introductory tutorial for numerical trajectory optimization with a focus on direct collocation methods. These methods are relatively simple to understand and effectively solve a wide variety of trajectory optimization problems. Throughout the paper we illustrate each new set of concepts by working through a sequence of four example problems. We start by using trapezoidal collocation to solve a simple one-dimensional toy problem and work up to using Hermite--Simpson collocation to compute the optimal gait for a bipedal walking robot. Along the way, we cover basic debugging strategies and guidelines for posing well-behaved optimization problems. The paper concludes with a short overview of other methods for trajectory optimization. We also provide an electronic supplement that contains well-documented MATLAB code for all examples and methods presented. Our primary goal is to provide the reader with the resources necessary to understand and successfully implement their own direct collocation methods. (An erratum is attached.)},
+	number = {4},
+	urldate = {2022-03-15},
+	journal = {SIAM Review},
+	author = {Kelly, Matthew},
+	month = jan,
+	year = {2017},
+	note = {Publisher: Society for Industrial and Applied Mathematics},
+	keywords = {34, 37, 49, 90, 97, direct collocation, direct transcription, optimal control, robotics, trajectory optimization, tutorial},
+	pages = {849--904},
+}
+
+@misc{brockie_predictive_2021,
+	title = {Predictive {Simulation} of {Musculoskeletal} {Models} {Using} {Direct} {Collocation}},
+	language = {en},
+	author = {Brockie, Samuel George},
+	year = {2021},
+}

docs/requirements.txt

@@ -1,2 +1,3 @@
 furo>=2023.5.20
 sphinx>=6.1.3
+sphinxcontrib-bibtex>=2.6.1