Pymole feature add 1d operators

[cpaolini]

What type of PR is this? (check all applicable)

• Refactor
• [ X ] Feature
• Bug Fix
• Optimization
• Example
• Documentation

Description

The pymole-feature-add-1d-operators branch introduces an initial Python implementation of MOLE’s mimetic operators. This branch features an installable pymole package, multidimensional grid generation, partial 2-D/3-D support, boundary-condition infrastructure, tests, examples, documentation, and Python CI. Classes include a 1-D, 2-D, and 3-D Grid; 1-D, 2-D, and partial 3-D Gradient; 1-D and 2-D Divergence; 1-D and 2-D Laplacian; 2-D Curl; and RobinBoundaryCondition. The branch adds 47 Python unit tests that cover: Grid construction, spacing, dimensions, validation, and unpacking; Operator matrix dimensions; Rejection of unsupported accuracy orders or undersized grids; Zero derivatives of constant fields; Basic linear and quadratic-field behavior; The identity L=DG and the basic 2-D curl behavior are included. The updated ci.yml runs these tests on Python 3.10, 3.11, and 3.12. A separate Python documentation workflow builds Sphinx documentation and deploys the generated HTML on pushes. A 1D Poisson's equation example is provided.

Related Issues & Documents

• [ X ] I have created an Issue that is paired with this PR
• Closes Add Python MOLE to repository #337

QA Instructions, Screenshots, Recordings

$ pytest python/tests
============================= test session starts ==============================
platform linux -- Python 3.10.21, pytest-9.1.1, pluggy-1.6.0
rootdir: /home/runner/work/mole/mole/python
configfile: pyproject.toml
collected 47 items

python/tests/test_curl.py ... [ 6%]
python/tests/test_divergence.py ....... [ 21%]
python/tests/test_gradient.py ............. [ 48%]
python/tests/test_grid_utility.py ................ [ 82%]
python/tests/test_laplacian.py ........ [100%]

============================== 47 passed in 0.42s ==============================

Keep-open request

• I am requesting maintainer review for keep-open.

Reason:

Added/updated tests?

_We encourage you to test all code included with MOLE, including examples.

• [ X ] Yes
• No, and this is why: please replace this line with details on why tests
  have not been included
• I need help with writing tests

Read Contributing Guide and Code of Conduct

• [ X ] 📖 I have read the MOLE Contributing Guide: https://github.com/csrc-sdsu/mole/blob/main/CONTRIBUTING.md
• [ X ] 📖 I have read the MOLE Code of Conduct: https://github.com/csrc-sdsu/mole/blob/main/CODE_OF_CONDUCT.md

[optional] Are there any post deployment tasks we need to perform?

No

[optional] What gif best describes this PR or how it makes you feel?

[Tony-Drummond]

The instructions in the README.md now work as expected. All the tests run and also the example.

[Tony-Drummond]

and python/src/pymole/ is where all Python implementations of the MOLE operators and grids are located.
At first this organization may suggest that other python implementations of MOLE could co-exist under the python subdirectory, which is a good design consideration for future extensibility. Under this software design, the specific SDSU pymole implementation is under python/src/pymole/ However, pymole's examples and tests are all under python. I recommend that to keep up with the software extensibility design consideration, examples and tests be placed also in python/tests/pymole and python/examples/pymole

@Tony-Drummond src/ isn't a folder or space for multiple implementations. It's the PyPA src-layout convention (see: https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/). The intention with this layout (besides following Python standards) is to prevent tests and examples from accidentally importing the working tree instead of the installed package. @cpaolini we should stick to a single example location. My preference is examples/python since we already have examples for C++and MATLAB/Octave in examples/

@aboada I did not suggest to use /src, if you read carefully my comment suggests At first this organization may suggest that other python implementations of MOLE could co-exist under the python subdirectory, which is a good design consideration for future extensibility. which is very different from how you interpreted. Let me expand.

According to the Python Enhancement Proposals, PEP 518 and PEP 621, PEPs for minimal package requirements and storing the project metadata, respectively, the following scenario is possible:

python/
├── pyproject1.toml       # build system, dependencies, project 1 metadata 
├──  pyproject2.toml     # build system, dependencies, project  2 metadata 
└── pyproject3.toml     # build system, dependencies, project  3 metadata

The above requires special handling to accommodate for build tools looking for a single pyproject.toml file (e.g., have a script that the user can set one of the *.toml files as the package to install for pip, build. Alternatively, use tomlib to build one package at a time, etc.)

Another, possibility is to adopt this directory structure:

python/
├── project1/
│   └── pyproject.toml
├── project2/
│   └── pyproject.toml
└── project3/
    └── pyproject.toml

Then users can cd projectX and pip install . (or python -m build, etc.) and all projects are independently buildable with zero custom tooling.

I hope the details above helps. Definitively, I never intended to suggest the use a single /src for multiple python implementations of MOLE.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cpaolini]

@aboada Used Ruff to apply formatting to elliptic1D.py.

[Tony-Drummond]

@cpaolini Since this PR has had a lot of activity, I am summarizing here all the changes that you have already implemented:

• Reviewed installation instructions in README.md (requester: @Tony-Drummond)
• pyproject.toml now includes package/library dependencies (requester: @Tony-Drummond)
• Changes to examples/matlab_octave/elliptic1D.m have been reverted (requester: @aboada )
• examples/python/simple_operators_check.py has been removed (requester: @aboada )
• @aboada suggested reviewing all .gitkeep files
• Explicit definition of PYTHONPATH have been removed from elliptic1D.py (requester: @aboada )
• @aboada suggested rewriting this example in a more Pythonic way (pending for future work in Issue Rewriting python/examples/elliptic1D.py to be Pythonic #474)
• @aboada suggested reviewing unused imports in example
• File naming convention. PEP 8 recommends PascalCase/CapWords for class names (@Tony-Drummond agrees, @aboada ?)
• Included MOLE version (for now it has v1.2.0)
• python/LICENSE has been deleted.
• apply ruff formatting (requester: @aboada ) @cpaolini Used Ruff to apply formatting to elliptic1D.py.

I believe that the unchecked items above is all we need before merging this PR. The current deadline is before Thursday this week so it can be included with the MOLE 1.3.0 release.

[aboada]

and python/src/pymole/ is where all Python implementations of the MOLE operators and grids are located.
At first this organization may suggest that other python implementations of MOLE could co-exist under the python subdirectory, which is a good design consideration for future extensibility. Under this software design, the specific SDSU pymole implementation is under python/src/pymole/ However, pymole's examples and tests are all under python. I recommend that to keep up with the software extensibility design consideration, examples and tests be placed also in python/tests/pymole and python/examples/pymole

@Tony-Drummond src/ isn't a folder or space for multiple implementations. It's the PyPA src-layout convention (see: https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/). The intention with this layout (besides following Python standards) is to prevent tests and examples from accidentally importing the working tree instead of the installed package. @cpaolini we should stick to a single example location. My preference is examples/python since we already have examples for C++and MATLAB/Octave in examples/

@aboada I did not suggest to use /src, if you read carefully my comment suggests At first this organization may suggest that other python implementations of MOLE could co-exist under the python subdirectory, which is a good design consideration for future extensibility. which is very different from how you interpreted. Let me expand.

According to the Python Enhancement Proposals, PEP 518 and PEP 621, PEPs for minimal package requirements and storing the project metadata, respectively, the following scenario is possible:

python/
├── pyproject1.toml       # build system, dependencies, project 1 metadata 
├──  pyproject2.toml     # build system, dependencies, project  2 metadata 
└── pyproject3.toml     # build system, dependencies, project  3 metadata

The above requires special handling to accommodate for build tools looking for a single pyproject.toml file (e.g., have a script that the user can set one of the *.toml files as the package to install for pip, build. Alternatively, use tomlib to build one package at a time, etc.)

Another, possibility is to adopt this directory structure:

python/
├── project1/
│   └── pyproject.toml
├── project2/
│   └── pyproject.toml
└── project3/
    └── pyproject.toml

Then users can cd projectX and pip install . (or python -m build, etc.) and all projects are independently buildable with zero custom tooling.

I hope the details above helps. Definitively, I never intended to suggest the use a single /src for multiple python implementations of MOLE.

My concern really is a clear separation of concerns between source, examples and tests. It seems you are onboard with that so we're aligned. I don't disagree with what you are saying.

The potential approaches you are suggesting are fine by me as long as we respect the mentioned separation of concerns.

[aboada]

Thanks for the summary, @Tony-Drummond. From my end:

• examples/python/simple_operators_check.py

I think there was value in this file. Perhaps it can be added as an integration test of some sort in the future. No issues with the removal.

@aboada suggested reviewing all .gitkeep files

Not a blocker for me, but having .gitkeep files in folders with checked-in files provides no value and pollutes the codebase. I still suggest removal.

@aboada suggested rewriting this example in a more Pythonic way (pending for future work)

I would want to know if there was an issue created for it. If not, we should create one. It should be easy to write this example in a Pythonic way, which will provide value for the library.

File naming convention. PEP 8 recommends PascalCase/CapWords for class names (@Tony-Drummond agrees, @aboada ?)

As stated in my comment, consistency is key. Moreover, we should adhere to PEP8 recommendation for module (file) names.

---

I think the only blocker for me is the filenames. They should be all snake_case following PEP8 conventions.

[cpaolini]

@aboada The files BoundaryCondition.py and RobinBoundaryCondition.py were renamed to use snake_case, becoming boundary_condition.py and robin_boundary_condition.py.

[cpaolini]

@aboada All six .gitkeep files have been removed.

[valeriabarra]

Hi! I really appreciate this contribution and all of the reviewer's work. However, @Tony-Drummond , please in the future refrain from merging such a long history of commits in the main branch without first a proper rebasing/squashing with a reduction of the number of commits. It is very important to keep the main branch history as clean as possible and not to pollute it with large PRs. Every large PR, after being reviewed and approved, should be reduced to a minimum number of meaningful, atomic commits, before merging. Thank you!