[General] Review Comments Before JOSS Acceptance #795

Activity

1. giovannifereoli

   assigned

   ocots

   on Jun 1, 2026
2. ocots commented on Jun 4, 2026

   

   ocots

   on Jun 4, 2026

   Member

   More actions

   Thanks @giovannifereoli for the very encouraging feedback and for the careful reading of both the package and the paper. Below we address each point in turn.

   ---

   Summary of changes

   The following files have been modified in the joss branch (see the joss folder on GitHub for a complete view):

   • joss/paper.md, joss/paper.pdf – Added a Testing and quality assurance paragraph to the Software Design section, and removed the redundant mention of GitHub Actions from the Acknowledgements section.
   • README.template.md – Added a Motivation section (reference-free Statement of Need) and a Testing note. The generated README.md will be updated via the centralized workflow.
   • docs/src/index.md – Added a Motivation section and a Testing section.

   ---

   Mandatory

   1. Statement of Need in the documentation

   We agree that the motivation should be easy to find. Rather than copying the full Statement of Need into the documentation (where the embedded list of references to other tools would quickly become outdated), we have distilled it into a single, reference-free paragraph describing the guiding philosophy of the package and the gap it fills. This paragraph has been added as a new Motivation section:

   • on the front page of the documentation (docs/src/index.md), right after the introduction;
   • in the project README (README.template.md, from which README.md is generated by our centralized workflow).

   The added paragraph reads:

   The guiding philosophy of OptimalControl.jl is to offer, to our knowledge, the only Julia package that unifies both direct and indirect methods for optimal control within a single, coherent framework. This fills a gap in a landscape where existing tools are fragmented across programming languages and paradigms, and are usually restricted to a single family of methods. The package provides a domain-specific language that closely matches mathematical notation, together with multiple discretization schemes and shooting methods, and planned support for homotopy continuation methods. Its modeler–solver separation makes it agnostic to the underlying NLP modeling backend and optimization solver, and enables seamless execution on both CPU and GPU with minimal user intervention. Combined with an ecosystem of domain-specific applications, tutorials, and benchmarking tools, this design targets researchers and engineers working in optimal control, control theorists developing new algorithms, and students learning the field through interactive tutorials.

   The full Statement of Need with references to the broader software landscape remains in the paper.

   2. Testing approach in the documentation

   We have added a dedicated Testing section to the documentation front page (docs/src/index.md) and a Testing note to the README. They summarize:

   • the layered strategy in our multi-repository ecosystem: each sub-package (CTBase, CTParser, CTModels, CTDirect, CTSolvers, CTFlows) has its own test suite combining unit tests, integration tests, and code-quality checks (e.g. with Aqua.jl), while the umbrella package OptimalControl.jl adds strong end-to-end integration tests solving complete problems by both direct and indirect methods;
   • continuous integration on Linux, macOS, and Windows, on both CPU and GPU (via a self-hosted CUDA runner), through reusable workflows centralized in CTActions;
   • code coverage tracked on Codecov;
   • breakage tests that guard downstream packages and applications against regressions on pull requests;
   • a local registry, ct-registry, used to distribute beta versions during development;
   • the ongoing effort to use OptimalControlProblems.jl as a curated problem bank for non-regression on complex problems.

   We also note in the documentation, as already disclosed in the AI Usage Disclosure section of the paper, that part of the test code is written with the help of AI agents, always under human review.

   3. Testing approach in the paper

   We have added a Testing and quality assurance paragraph to the Software Design section of the paper, summarizing the same layered testing strategy, the multi-platform CPU/GPU continuous integration based on the centralized CTActions workflows, code coverage, downstream breakage testing, and the OptimalControlProblems.jl-based non-regression goal.

   ---

   Nice to have

   1. Small illustrative example in the paper

   A self-contained illustrative example combining direct and indirect approaches is already referenced in the paper (Illustrative Example section). As agreed with the editor (see this comment), the example was moved to a companion repository, joss-oc-example, and archived on Zenodo. The rationale is twofold: a short illustrative example is already shown on the front page of the documentation, and a fully worked example demonstrating both the direct and indirect scope of the package quickly becomes long; keeping it in a separately versioned, archived repository avoids the risk of it becoming outdated within the paper.

   ---

   Question / concern

   1. What happens for non-Hamiltonian flows?

   This is work in progress. We are currently refactoring CTFlows.jl, which will change substantially and add support for non-Hamiltonian flows. In particular, it will allow constructing flows directly from an optimal control problem by providing a control law either in open loop (u(t)) or in closed loop as a state feedback (u(x)), in addition to the current control depending on state and co-state (u(x, p)).

   👍React with 👍1Reacted by Jean-Baptiste Caillau
3. ocots

   assigned

   jbcaillau

   on Jun 4, 2026
4. giovannifereoli commented on Jun 4, 2026

   

   giovannifereoli

   on Jun 4, 2026

   Author

   More actions

   Thanks for the answers, everything sounds good!

   Just to iterate on a few points:

   1. Where are these changes made so I can take a look? Is there already a merge request?
   2. I think the paper and documentation should include a short disclaimer about non-Hamiltonian flows, to clearly point out current limitations and possible future work. I don’t remember seeing one!
   3. What about adding some code examples to the documentation, or even directly in the repo? A Jupyter notebook would be great, even if it is just based on the Zenodo example.
5. ocots commented on Jun 11, 2026

   

   ocots

   on Jun 11, 2026

   Member

   More actions

   Thanks @giovannifereoli for the follow-up comments and for helping us improve the paper and documentation further. Below we address each point in turn.

   ---

   1. Where are these changes made?

   The changes from the first round of review were committed directly to the joss branch. You can view them at:

   • Commit ec62947
   • Commit 1e8f610

   There is a pull request from joss to main (#762) that will merge these changes once the review process is complete: #762. The documentation preview for this PR is available at: https://control-toolbox.org/OptimalControl.jl/previews/PR762/

   ---

   2. Disclaimer about non-Hamiltonian flows

   You are right that this limitation should be clearly stated. We have added disclaimers in the paper and in the dedicated flow tutorial. The changes are gathered in PR #800 (joss-reviewer-giovannifereoli → joss). The documentation preview for this PR will be available at: https://control-toolbox.org/OptimalControl.jl/previews/PR800/

   In the paper (joss/paper.md), we extended the Indirect methods bullet in the Software Design section with:

   Currently, indirect methods are limited to Hamiltonian flows, where the feedback control law depends on both state and costate; support for non-Hamiltonian flows (open-loop or state-feedback control laws) is under active development.

   In the dedicated flow tutorial (docs/src/manual-flow-ocp.md), we added a prominent admonition at the very top of the page, before any code example:

   Current limitation: Currently, from an optimal control problem, only Hamiltonian flows can be constructed, i.e. the control law must be provided in feedback form depending on both state and costate: u(x, p). An active refactoring is under way to extend support to non-Hamiltonian flows, in particular open-loop control laws u(t) and state feedback control laws u(x).

   This last placement is the most visible for users who are actually working with the Flow function from an optimal control problem, since it appears before any example.

   ---

   3. Code examples in the documentation

   We believe the documentation already provides substantial code examples at several levels of complexity.

   Front page and README: A minimal self-contained example (double integrator energy minimization) is shown directly on the documentation front page and in the README, illustrating the core workflow: define a problem with @def, solve it, and plot the solution.

   Six basic examples: The documentation includes six standalone examples covering a broad range of problem types, each solved by both direct and indirect methods:

   • Energy minimisation (smooth, unconstrained)
   • Time minimisation
   • Control-free problems
   • Problems with an optimisation variable
   • Singular control
   • State-constrained problems (order 1 and 2)

   Online tutorials: Tutorials.jl provides a comprehensive online documentation with more advanced examples (Goddard rocket, Model Predictive Control, etc.), actively maintained alongside the package.

   Application pages: The applications section presents richer research-level studies built on top of OptimalControl.jl, covering domains such as aerospace, medical imaging, and quantum control.

   Interactive Jupyter notebook: The companion repository joss-oc-example (archived on Zenodo) now includes a Jupyter notebook example.ipynb that can be run directly in the browser via Binder: . This notebook demonstrates the full direct + indirect workflow on a constrained energy minimization problem.

   ---

   We hope these additions address your concerns. Thank you again for your careful review and helpful suggestions.
6. giovannifereoli commented on Jun 11, 2026

   

   giovannifereoli

   on Jun 11, 2026

   Author

   More actions

   Yes, sounds good to me! Thanks a lot guys for your work!

   👍React with 👍1Reacted by Olivier Cots
7. giovannifereoli commented on Jun 11, 2026

   

   giovannifereoli

   on Jun 11, 2026

   Author

   More actions

   Once the PR is complete please give me an heads up, I'll finish my checklist and give my green light!
8. ocots commented on Jun 11, 2026

   

   ocots

   on Jun 11, 2026

   Last edited by ocots

   Member

   More actions

   Thank you for so much enthusiasm! I have merged the PR: #800.

   I am waiting for:

   • Reviewer 2 and associated PR: joss: address reviewer 2 first-round comments (paper.md) #801
   • Reviewer 3.
9. giovannifereoli commented on Jun 11, 2026

   

   giovannifereoli

   on Jun 11, 2026

   Author

   More actions

   What about #762?

   I guess this one contains the other commits we were talking about?
10. ocots commented on Jun 11, 2026

    

    ocots

    on Jun 11, 2026

    Member

    More actions

    Yes exactly, #762 contains all the other commits. I didn't think at first to open a PR! I will merge #762 when all the reviewers are ok.
11. ocots commented on Aug 1, 2026

    

    ocots

    on Aug 1, 2026

    Member

    More actions

    @giovannifereoli Everything is merged in #762. Last PR to merge if editor is ok.
12. ocots

    closed this as completedon Aug 1, 2026