Testing and CI integration for LyoPronto from SECQUOIA

[bernalde]

This pull request introduces a comprehensive overhaul of CI/CD configuration, project documentation, and development guidelines for the LyoPRONTO project. The changes centralize Python version management, add detailed instructions for contributors and AI tools, and implement robust, flexible workflows for testing and documentation deployment. The updates are designed to streamline development, enforce physics and coding standards, and improve reliability and maintainability.

Continuous Integration & Testing Improvements:

• Centralized Python version management for all CI workflows via .github/ci-config/ci-versions.yml, ensuring consistency and simplifying future upgrades. [1] [2] [3] [4] [5]
• Added three new GitHub Actions workflows:
  • pr-tests.yml: Smart PR testing that runs fast tests for draft PRs and full coverage for ready PRs, with coverage upload to Codecov.
  • slow-tests.yml: Manual workflow for running slow optimization tests and/or the full suite, with coverage reporting.
  • tests.yml: Main branch workflow running the complete test suite with coverage for pushes to main and dev-pyomo.
• Updated docs.yml workflow to read Python version from the centralized config and improved deployment steps for documentation. [1] [2]

Documentation & Contributor Guidance:

• Added .github/copilot-instructions.md with extensive project context, physics variable conventions, output formats, common pitfalls, Pyomo development guidelines, testing standards, and references for new contributors and AI tools.
• Added .cursorrules file specifying AI code generation preferences, physics standards, variable naming, testing requirements, and file organization to guide AI assistants and developers.
• Introduced .aidigestignore to deprioritize or ignore generated, binary, and temporary files for AI summarization and tooling.

Other Notable Updates:

• Improved workflow reliability and maintainability by making test and deployment steps more explicit and robust (e.g., Python version, dependency management, coverage reporting). [1] [2] [3] [4] [5]

These changes collectively enhance developer experience, enforce project standards, and ensure a smooth transition to Pyomo-based optimization.

---

References:
[1] [2] [3] [4] [5] [6] [7] [8] [9]

[Ickaser]

Is it intentional that you don't deploy to GitHub pages here?

[bernalde]

I'm not deploying it in every push, but we can revert it if you feel it necessary. I was avoiding this in the SECQUOIA branch to make development faster

[Ickaser]

I will need to download some of these changes and look through it more carefully, 168 files (!) is apparently too many for GitHub to load comfortably in the online interface.

A couple overall questions:

• What is the intended documentation setup here?
• With all these test cases, will those by default be installed once this is eventually made available through PyPI or conda-forge? I haven't published a package that way so I just don't know the regular workflow there.
• I see the unit annotations have been standardized to a new format; is there a unit package you have in mind that will read those or is it just for the developer's benefit?

[Ickaser]

And further: there seems to be a lot of material in the docs folder that might be more useful to an AI tool than to a person reading it. Is this expected? I see other areas that I already know I would like to revise; will these be overwritten by an AI tool if I am not careful? Do I need to ensure that my changes are somehow compatible with what tools expect?

I mean these questions sincerely, not as a criticism--please enlighten me!

[bernalde]

Let me address your comments:

• I like numpy style for documenting functions, but for the docs of the overall package, I tried not to touch those. Is that what you refer to?
• The whole repo would become available if we turn this into a package downloadable via conda or pip. We might need to do some cleanup before that, if that is the goal of this repository
• Good observation. I am slowly inching toward creating the units in a format that is compatible with pint. Now, the [unit] notation is my personal and very opinionated preference. We can revert it if we want
• The docs folder that I moved a bunch of .md files serves as a human but mostly AI-readable document for integrated development. You can feel free to change them, but they will mainly affect how coding agents will interact with your repository. We can give it a good clean between us if you prefer, but I like it because it also keeps track of the development history.

[Ickaser]

Responding:

• For the docs, I was trying to understand whether the AI-friendly docs were meant to be human-readable. I am not committed to any particular style guide for docstrings (can't even remember which I picked for the few I wrote by hand, might be numpy).
• Publication to pip and conda is a goal for making this package more accessible, so it would be good to keep the package size minimal where possible, but from what I see at here extra images in docs, etc. shouldn't be a problem
• I would be fully on board with using pint for dealing with units. I don't remember whether or not that plays nicely with arrays of heterogeneous units as are used on the current output.
• Having read through a few of the AI-generated documents, I think that I would prefer these not be committed to the main branch, since they create so much noise and a close reading indicates they contain hallucinations that are incorrect. For example, ARCHITECTURE.md messes up the argument order of the function Kv_FUN and adds Lck as an argument, which (setting aside the physics) is not true of the code. Of course you can keep them around in your copy, etc., but I think I want to be a little more careful with what makes it into this official repo.

Having taken a little bit longer look (and time to think), I have a few other comments by topic:

• I am excited about having a more exhaustive test suite here. But the fast/slow test split seems odd to me, since the entire test suite is still less than 15 minutes. Is this something you chose by design?
• There is a new benchmarks folder with what looks like speed comparisons between pyomo and scipy, which seems like valid research material but not strictly necessary to code functioning (particularly since it contains some results as images). Is there a reason to merge that here?

I think in general I am excited about adding a proper test suite, so I would readily merge a PR with just the tests. I want to be more careful about reviewing docs and examples, since I want those to be 100% accurate and expect to either write these by hand or review every word that an LLM puts down; in the current form, there is simply too much of these to look through at once.

[bernalde]

Awesome, let mw address each comment

• For the docs, I was trying to understand whether the AI-friendly docs were meant to be human-readable. I am not committed to any particular style guide for docstrings (can't even remember which I picked for the few I wrote by hand, might be numpy).

Not now, but maybe it is a good idea for us to settle on something rather soon

• Publication to pip and conda is a goal for making this package more accessible, so it would be good to keep the package size minimal where possible, but from what I see at here extra images in docs, etc. shouldn't be a problem

Great, let's make it part of a future plan, maybe list that as a

• I would be fully on board with using pint for dealing with units. I don't remember whether or not that plays nicely with arrays of heterogeneous units as are used on the current output.

They are supposed to work particularly well in those cases. Once again, we can leave it as a future development

• Having read through a few of the AI-generated documents, I think that I would prefer these not be committed to the main branch, since they create so much noise and a close reading indicates they contain hallucinations that are incorrect. For example, ARCHITECTURE.md messes up the argument order of the function Kv_FUN and adds Lck as an argument, which (setting aside the physics) is not true of the code. Of course you can keep them around in your copy, etc., but I think I want to be a little more careful with what makes it into this official repo.

This is great to know, as it would be really useful for me to include in my local dev environment. I can't think of a better way of dealing with these than receiving some feedback through the review and before merging, we delete them from this branch! Thank you

Having taken a little bit longer look (and time to think), I have a few other comments by topic:

• I am excited about having a more exhaustive test suite here. But the fast/slow test split seems odd to me, since the entire test suite is still less than 15 minutes. Is this something you chose by design?

This was completely arbitrary: 15 minutes was too long for my own patience lol. The split was based on my own taste and we can discuss it

• There is a new benchmarks folder with what looks like speed comparisons between pyomo and scipy, which seems like valid research material but not strictly necessary to code functioning (particularly since it contains some results as images). Is there a reason to merge that here?

That was not supposed to be there. Oops, I was planning on having that for a future PR and our presentation

I think in general I am excited about adding a proper test suite, so I would readily merge a PR with just the tests. I want to be more careful about reviewing docs and examples, since I want those to be 100% accurate and expect to either write these by hand or review every word that an LLM puts down; in the current form, there is simply too much of these to look through at once.

I agree with you. I would only ask for a revision of as much as you can provide (which is already a lot). If you tell me to delete those docs, I will do that now, but I think that having some of that knowledge captured, particularly for future development, is useful. Just let me know how to proceed, and we'll do it.

[Ickaser]

Awesome, let mw address each comment

• For the docs, I was trying to understand whether the AI-friendly docs were meant to be human-readable. I am not committed to any particular style guide for docstrings (can't even remember which I picked for the few I wrote by hand, might be numpy).

Not now, but maybe it is a good idea for us to settle on something rather soon

• Publication to pip and conda is a goal for making this package more accessible, so it would be good to keep the package size minimal where possible, but from what I see at here extra images in docs, etc. shouldn't be a problem

Great, let's make it part of a future plan, maybe list that as a

• I would be fully on board with using pint for dealing with units. I don't remember whether or not that plays nicely with arrays of heterogeneous units as are used on the current output.

They are supposed to work particularly well in those cases. Once again, we can leave it as a future development

• Having read through a few of the AI-generated documents, I think that I would prefer these not be committed to the main branch, since they create so much noise and a close reading indicates they contain hallucinations that are incorrect. For example, ARCHITECTURE.md messes up the argument order of the function Kv_FUN and adds Lck as an argument, which (setting aside the physics) is not true of the code. Of course you can keep them around in your copy, etc., but I think I want to be a little more careful with what makes it into this official repo.

This is great to know, as it would be really useful for me to include in my local dev environment. I can't think of a better way of dealing with these than receiving some feedback through the review and before merging, we delete them from this branch! Thank you

Having taken a little bit longer look (and time to think), I have a few other comments by topic:

• I am excited about having a more exhaustive test suite here. But the fast/slow test split seems odd to me, since the entire test suite is still less than 15 minutes. Is this something you chose by design?

This was completely arbitrary: 15 minutes was too long for my own patience lol. The split was based on my own taste and we can discuss it

• There is a new benchmarks folder with what looks like speed comparisons between pyomo and scipy, which seems like valid research material but not strictly necessary to code functioning (particularly since it contains some results as images). Is there a reason to merge that here?

That was not supposed to be there. Oops, I was planning on having that for a future PR and our presentation

I think in general I am excited about adding a proper test suite, so I would readily merge a PR with just the tests. I want to be more careful about reviewing docs and examples, since I want those to be 100% accurate and expect to either write these by hand or review every word that an LLM puts down; in the current form, there is simply too much of these to look through at once.

I agree with you. I would only ask for a revision of as much as you can provide (which is already a lot). If you tell me to delete those docs, I will do that now, but I think that having some of that knowledge captured, particularly for future development, is useful. Just let me know how to proceed, and we'll do it.

As it stands, I think the easiest way forward is to split this PR into multiple PRs as follows:

• Testing folders & /src (since these are already approved)
• Docs + AI help files (e.g. cursorrules)
• Examples (possibly with one of the first two)
• Benchmarks for future PR if desired

That way I can merge the tests as is, and doing so will cut down the number of files enough that are changed--hopefully enough that in the docs PR I can provide inline suggestions of what is okay, what is wrong, what needs to be deleted, etc.; currently there are so many new files that GitHub's interface struggles to handle the suggestions.

I can also provide some comments/notes/review on the docs as they stand here, it will just need to be plaintext comments here which might be harder to associate with their context

[Ickaser]

I reviewed some of the tests. This should be considered non-exhaustive, but is a start. I would really appreciate breaking this PR up, because although I managed to load things better in VSCode than in GitHub's web interface, it's still giving me problems because the diff is so large.