Merge pull request #221 from nbelakovski/pyprima

Include Python implementation of COBYLA and associated CI test. Thank @nbelakovski for this great contribution to PRIMA! -Zaikun

Author: zaikunzhang

.github/actions/spelling/allow.txt

@@ -2261,3 +2261,40 @@ TESTQUAD
 WAITALL
 xcodebuild
 ICX
+Belakovski
+allclose
+argmin
+biggs
+CHEC
+checkbreak
+chisti
+codebases
+cov
+cqai
+cqi
+degenlpb
+errinbar
+fhisti
+hstack
+isneginf
+isposinf
+joptcandidate
+jth
+Kbreak
+mgh
+mmm
+nanargmax
+tenbars
+tfi
+pyprima
+primasum
+primapow
+autouse
+SYNTHES
+pytestmark
+misra
+polak
+loadgroup
+rosen
+newx
+COBYQA

.github/workflows/test_pyprima.yml

@@ -0,0 +1,55 @@
+name: Test PyPRIMA
+
+on:
+  # Trigger the workflow on push or pull request
+  #push:
+  pull_request:  # DANGEROUS! MUST be disabled for self-hosted runners!
+  # Trigger the workflow by cron. The default time zone of GitHub Actions is UTC.
+  schedule:
+    - cron: '0 16 4-31/4 * *'
+  # Trigger the workflow manually
+  workflow_dispatch:
+
+
+jobs:
+
+  test:
+    name: Run PyPRIMA tests
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/[email protected]
+
+      - name: Setup Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r pyprima/tests/requirements.txt
+
+      - name: Conduct the test
+        shell: bash
+        run: |
+            cd pyprima
+            # Need editable mode for coverage to work correctly
+            python -m pip install --editable .
+            pytest --cov=src --cov-report=html tests/
+
+
+      - name: Store artifacts
+        uses: actions/upload-artifact@v4
+        id: artifact-coverage
+        with:
+          name: coverage-html-${{ matrix.os }}
+          path: pyprima/htmlcov/*
+
+      - name: Output artifact URL
+        run:  echo 'Artifact URL is https://github.com/nbelakovski/prima/actions/runs/${{ github.run_id }}/artifacts/${{ steps.artifact-coverage.outputs.artifact-id }}'

pyprima/.gitignore

@@ -0,0 +1,2 @@
+pycutest_cache_holder
+out

pyprima/README.md

@@ -0,0 +1,66 @@
+To develop, `cd` into the `src` directory and run
+
+```pip install --editable .```
+
+This will install prima locally in an editable fashion. From there you can run the examples/cobyla/cobyla_example.py (from any directory) and go from there.
+
+## Style notes
+
+- Most of the comments are copied from Fortran verbatim, except in cases where they need to modified due to specifics of the Python language. In these cases a note will be made of the difference between Fortran and Python
+  - Rationale:
+      - The main purpose of this is to keep the Python and Fortran codebases as similar as possible.
+- For determining the dimensions of an array, we exclusively use `np.size` instead of `np.shape` or `some_array.shape` or `len`
+  - Rationale:
+    - Fortran uses `SIZE` so this helps us to be as consistent with the Fortran code as possible.
+
+## A note on Fortran's `maxval`, `maximum`, and `maxval` and their Python equivalents
+
+| Fortran   | Python       | Return value |
+|-----------|--------------|--------------|
+| `maxval`  | `max`        | scalar       |
+| `maximum` | `np.max`     | scalar       |
+| `max`     | `np.maximum` | vector       |
+
+The difference between `maxval` and `maximum` is that `maximum` will return NaN if the input contains NaN. Python's `max`
+and numpy's `np.max` have a similar distinction.
+
+Fortran's `max` and numpy's `mp.maximum` accept two arguments, either of which can be a scalar or an array,
+and returns an elementwise maximum of the two arguments. In the case of a scalar and an array argument it
+returns an elementwise maximum of the scalar and each element of the array.
+
+This note applies to `minval`, `minimum`, and `min` as well.
+
+
+## A note on indices
+
+Consider the following Fortran code
+
+```
+do i=0:5
+  print *, *
+end do
+```
+
+It can be easily and automatically translated to Python as
+
+```
+for i in range(0, 6):
+  print(i)
+```
+
+Now consider the following similar loop
+
+```
+do i=1:5
+  print *, some_array(i)
+end do
+```
+
+This can be translated to Python as
+
+```
+for i in range(1, 6):
+  print(some_array[i-1])
+```
+
+This leads to awkward Python code, since the more pythonic code would range from 0 to 5, and the indexing would be `some_array[i]`. In order to make the Python code more usable, we will attempt to write more "pythonic" code, even though that makes the translation a little bit more difficult.

pyprima/profiles_vs_matlab/.gitignore

@@ -0,0 +1,2 @@
+pycutest_cache_holder
+out

pyprima/profiles_vs_matlab/README.md

@@ -0,0 +1,7 @@
+This folder contains scripts and utilities to run performance profiles of the PRIMA Python bindings against the PRIMA MATLAB bindings.
+
+In general we expect the performance profiles to show a straight line for both the output based and history based profiles since the underlying code is the same. However since there are bound to be some differences in how MATLAB and Python handle floating point arithmetic we expect to see a few cases where one might perform slightly "better" than the other.
+
+In order to use this you will need Python and MATLAB and in the MATLAB GUI you should have run setup.m from the root of the repo. If that has been completed you should be able to run the profiles with simply `python profiles.py`. By default no profiles will be run, so you need to specify which algorithm you'd like to run profiles for using any combination of `-b` for BOBYQA, `-c` for COBYLA, `-l` for LINCOA, `-n` for NEWUOA, and `-u` for UOBYQA. You can also use `-j#` to change the number of jobs used to run the problems. For example to run both UOBYQA and NEWUOA with 4 jobs, you would run `python profiles.py -nuj4`.
+
+It is not necessary to have a MATLAB window open to run the profiles. Each job will create an instance of the MATLAB engine for Python. Please note that this instance takes up about 500MB of memory so you may want to limit the number of jobs accordingly.