Adds C++ API's to simsopt documentation

[mbkumar]

This PR adds Simsopt++ C++ API's to simsopt documentation. Please take a look at https://simsopt.readthedocs.io/en/doxygen/. The C++ documentation appears at Simsopt++ C++ API and Simsopt++ C++ Internals buttons at the bottom of the left hand pane. Needs to be coordinated with #493 to make the organization in the Right Hand Panel consistent.

[mishapadidar]

I like the idea of a For Develoeprs section. I have a few general comments on organization.

1. We have two sections related to the API: API Reference: Public Functions and Classes and Full API Listing. Why do we have both? Is it possible to just have a single API?
2. If the Full API Listing was moved to the API section, then everything in the For Developers section is related to C++.
3. Generally, what do we see as the main use case of the For Developers section? Is it for reference, learning, links? There are other related sections like contributing to simsopt that are not in this section, probably because they have a different purpose.

[mbkumar]

1. In the User API Reference, we don't list some functions/classes of simsopt that are not relevant for users. Mainly to simplify the learning curve for the users. Full API listing shows all the classes and functions of simsopt and useful for developers.
2. Contributing to simsopt points to users on how to contribute to simsopt. Treat it as a stepping stone for users to become developers.
3. We can expand "For Developers" with additional content. There are few features in simsopt that we don't expand on, such as jax usage, XSIMD based optimization, caching mechanism in C++. In future we can expand on these topics in "For Developers" documentation.

Bharat Medasani

On Tue, May 6, 2025 at 2:52 PM Misha Padidar @.***> wrote:

mishapadidar left a comment (hiddenSymmetries/simsopt#495) https://github.com/hiddenSymmetries/simsopt/pull/495#issuecomment-2855593099

I like the idea of a For Develoeprs section. I have a few general comments on organization.

1. We have two sections related to the API: API Reference: Public Functions and Classes and Full API Listing. Why do we have both? Is it possible to just have a single API?
2. If the Full API Listing was moved to the API section, then everything in the For Developers section is related to C++.
3. Generally, what do we see as the main use case of the For Developers section? Is it for reference, learning, links? There are other related sections like contributing to simsopt that are not in this section, probably because they have a different purpose.

— Reply to this email directly, view it on GitHub https://github.com/hiddenSymmetries/simsopt/pull/495#issuecomment-2855593099, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA62VEAAG7K6PKEKT5F7ZYL25EAIXAVCNFSM6AAAAAB4RZTZPKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQNJVGU4TGMBZHE . You are receiving this because you authored the thread.Message ID: @.***>

[mishapadidar]

Thanks for the responses, those are great ideas. I think that we could remove the Public API and just have the full API in the API section. Perhaps we should get others to chime in here though, @andrewgiuliani @landreman @smiet Everything else looks good to me.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 92.02%. Comparing base (bc4cd29) to head (ea2041d). Report is 3 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #495   +/-   ##
=======================================
  Coverage   92.02%   92.02%           
=======================================
  Files          82       82           
  Lines       15957    15957           
=======================================
  Hits        14684    14684           
  Misses       1273     1273           

Flag	Coverage Δ
unittests	92.02% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[andrewgiuliani]

Is there a simple way to go from a function in the documentation directly to the corresponding code on github? I have never figured out a simple way to do this, so I typically just read directly the code + docstrings on github rather than use these readthedoc pages.

can we merge with master so can observe what it will look like with #493 now live?

[mbkumar]

That's sounds good

On Wed, May 7, 2025, 10:26 AM Misha Padidar @.***> wrote:

@.**** commented on this pull request.

Should we rename the section Developer Reference?

— Reply to this email directly, view it on GitHub https://github.com/hiddenSymmetries/simsopt/pull/495#pullrequestreview-2822606610, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA62VEAH7TDD6IRAYM7I6WL25I62TAVCNFSM6AAAAAB4RZTZPKVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDQMRSGYYDMNRRGA . You are receiving this because you authored the thread.Message ID: @.***>

[mbkumar]

@andrewgiuliani

[mishapadidar]

Two changes:

1. Can we move the Simsopt++ C++ API into the API section and rename it Simsopt C++ API?
2. Can we rename simsopt package in the API Reference to Simsopt Python API?

Otherwise the changes all look good

[mbkumar]

Done. https://simsopt.readthedocs.io/en/doxygen/