Changes for 1.2.0 from LUMC GitLab (#62)

* Add Python.NET codecs * Add unified `ZOS.connect` method * Add `ZOS.disconnect` method to disconnect from OpticStudio * Add support for OpticStudio 2024 R1 and Python 3.12 * Allow relative paths and check for their existence in `OpticStudioSystem.load` and `OpticStudioSystem.save_as` --------- Co-authored-by: LucVV <l.van_vught@lumc.nl> Co-authored-by: jwmbeenakker <j.w.m.beenakker@lumc.nl> Co-authored-by: Jan-Willem Beenakker <90187768+jwmbeenakker@users.noreply.github.com>
MREYE-LUMC · Jan 19, 2024 · b78a44c · b78a44c
1 parent d0220f5
commit b78a44c
Show file tree

Hide file tree

Showing 207 changed files with 85,766 additions and 18,802 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ["3.9", "3.10", "3.11"]
+        python: ["3.9", "3.10", "3.11", "3.12"]
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python
@@ -23,6 +23,8 @@ jobs:
         pip install build
     - name: Build package
       run: python -m build
+    - name: Install package
+      run: python -m pip install --find-links ./dist/ zospy
 
   lint-isort:
     runs-on: ubuntu-latest

diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml
@@ -23,9 +23,9 @@ jobs:
       contents: read
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
     - name: Install dependencies
@@ -35,28 +35,30 @@ jobs:
     - name: Build package
       run: python -m build
     - name: Upload dist
-      uses: actions/upload-artifact@v3.1.2
+      uses: actions/upload-artifact@v4
       with:
         name: zospy_dist
         path: "dist/"
 
   publish_to_pypi:
     name: Publish to PyPI
-
+    needs: build
     runs-on: ubuntu-latest
     environment: PyPI
 
+    permissions:
+      id-token: write
+
     steps:
     - name: Download dist
-      uses: actions/download-artifact@v2.1.1
+      uses: actions/download-artifact@v4
       with:
         name: zospy_dist
         path: dist
     - name: Publish package
-      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      uses: pypa/gh-action-pypi-publish@v1.8.11
       with:
         user: __token__
-        password: ${{ secrets.PYPI_API_TOKEN }}
 
   upload_to_github:
     name: Upload to GitHub
@@ -69,18 +71,18 @@ jobs:
 
     steps:
     - name: Download dist
-      uses: actions/download-artifact@v2.1.1
+      uses: actions/download-artifact@v4
       with:
         name: zospy_dist
         path: dist
     - name: Upload wheels to GitHub release
-      uses: svenstaro/upload-release-action@2.5.0
+      uses: svenstaro/upload-release-action@2.7.0
       with:
         tag: ${{ github.ref }}
         file: "dist/*.whl"
         file_glob: true
     - name: Upload dist to GitHub release
-      uses: svenstaro/upload-release-action@2.5.0
+      uses: svenstaro/upload-release-action@2.7.0
       with:
         tag: ${{ github.ref }}
         file: "dist/*.tar.gz"

diff --git a/.github/workflows/python-test-publish.yml b/.github/workflows/python-test-publish.yml
@@ -13,7 +13,7 @@ on:
   workflow_dispatch:
 
   release:
-    types: [created, edited, prereleased]
+    types: [prereleased]
 
 jobs:
   build:
@@ -23,9 +23,9 @@ jobs:
       contents: read
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
     - name: Install dependencies
@@ -35,27 +35,30 @@ jobs:
     - name: Build package
       run: python -m build
     - name: Upload dist
-      uses: actions/upload-artifact@v3.1.2
+      uses: actions/upload-artifact@v4
       with:
         name: zospy_dist
         path: "dist/"
 
-  publish_to_testpypi:      
+  publish_to_testpypi:
+    name: Publish to TestPyPI
     runs-on: ubuntu-latest
     needs: build
     environment: TestPyPI
 
+    permissions:
+      id-token: write
+
     steps:
     - name: Download dist
-      uses: actions/download-artifact@v2.1.1
+      uses: actions/download-artifact@v4
       with:
         name: zospy_dist
         path: dist
     - name: Publish package
-      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      uses: pypa/gh-action-pypi-publish@v1.8.11
       with:
         user: __token__
-        password: ${{ secrets.TESTPYPI_API_TOKEN }}
         repository_url: https://test.pypi.org/legacy/
         # If the release is already present, overwrite it
         skip_existing: true
@@ -70,13 +73,19 @@ jobs:
 
     steps:
     - name: Download dist
-      uses: actions/download-artifact@v2.1.1
+      uses: actions/download-artifact@v4
       with:
         name: zospy_dist
         path: dist
     - name: Upload wheels to GitHub release
-      uses: svenstaro/upload-release-action@2.5.0
+      uses: svenstaro/upload-release-action@2.7.0
       with:
         tag: ${{ github.ref }}
         file: "dist/*.whl"
         file_glob: true
+    - name: Upload dist to GitHub release
+      uses: svenstaro/upload-release-action@2.7.0
+      with:
+        tag: ${{ github.ref }}
+        file: "dist/*.tar.gz"
+        file_glob: true
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,16 +11,60 @@ ZOS-API can also be added in patch releases.
 
 ### Added
 
+### Fixed
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+## [[1.2.0]](https://github.com/MREYE-LUMC/ZOSPy/releases/tag/v1.2.0) - 2024-01-19
+
+### Added
+
+- New, unified, connection method `ZOS.connect`. This method replaces the existing connection methods
+  `ZOS.connect_as_extension`, `ZOS.create_new_application` and `ZOS.connect_as_standalone`.
+  The connection mode is passed as an argument and the primary system is always returned (!47) 
+- The OpticStudio installation directory can be manually specified using the `opticstudio_directory` 
+  parameter of the `ZOS` class. This is particularly useful if multiple OpticStudio versions are installed
+  on the same system and you want to use a specific version (!47)
+  - **Note:** when this parameter is used, the `ZOSAPI_NetHelper` is not loaded and `ZOS.ZOSAPI_NetHelper` 
+    remains unset.
+- `zospy.api.codecs` for customized conversions between ZOS-API types and Python types (!48)
+- `zospy.api.codecs.OpticStudioInterfaceEncoder` for automatic downcasting of certain common generic interfaces
+    to their implementation (e.g. the use of `__implementation__` is no longer needed) (!48)
 - MTF analysis: `huygens_mtf` (#55)
+- `pickup_chief_ray` solver (!38)
+- `ZOS.disconnect` to disconnect from OpticStudio (!47)
+- Support for OpticStudio 2024 R1 (!51)
+- Support for Python 3.12 (!54)
 
 ### Fixed
 
+- `OpticStudioSystem.load` fails silently when path is incorrect or relative (#34)
+- Saving after connecting in extension mode fails because `OpticStudioSystem._OpenFile` is not set.
+  When connecting in extension mode, `_OpenFile` is now set with the path to the opened system to prevent this (#41)
+
 ### Changed
 
 - Changed license to MIT (#57, #58) - 2023-12-22
+- Deleting a `zospy.zpcore.ZOS` object now automatically calls `ZOS.disconnect` (!47)
+- When connecting in extension mode, it is not necessary anymore to save the primary system with 
+  `OpticStudioSystem.save_as` before it can be saved with `OpticStudioSystem.save` (!47, #41)
+- `zospy.analyses.base.Analysis` now uses `zospy.api.codecs.OpticStudioInterfaceEncoder` to downcast
+    analysis interfaces to their implementation (!48)
+- Accept relative paths and check if the path exists in `OpticStudioSystem.load` and `OpticStudioSystem.save_as` (!50)
+- Use `zospy.constants.process_constant` for parsing the `from_column` argument of `zospy.solvers.surface_pickup`.
+  This column can now be specified as either a value from `zospy.constants` or a string (!53)
 
 ### Deprecated
 
+- `ZOS.connect_as_extension`, `ZOS.create_new_application` and `ZOS.connect_as_standalone`.
+  They have been replaced with `ZOS.connect` (!47)
+- `zospy.functions.nce.get_object_data` is deprecated because its task is now performed by
+    `zospy.api.codecs.OpticStudioInterfaceEncoder` (!48)
+
 ### Removed
 
 ## [[1.1.2]](https://github.com/MREYE-LUMC/ZOSPy/releases/tag/v1.1.2) - 2023-12-13

diff --git a/README.md b/README.md
@@ -1,5 +1,8 @@
 # ZOSPy
 
+[![PyPI - Version](https://img.shields.io/pypi/v/ZOSPy)](https://pypi.org/project/zospy)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FMREYE-LUMC%2FZOSPy%2Fmain%2Fpyproject.toml)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/MREYE-LUMC/ZOSPy/ci.yml)
 [![Documentation Status](https://readthedocs.org/projects/zospy/badge/?version=latest)](https://zospy.readthedocs.io/en/latest/?badge=latest)
 
 ## About
@@ -14,12 +17,13 @@ In addition to full access to all the OpticStudio fucntions through the ZOS-API,
 - Wrapper functions for several OpticStudio analyses in `zospy.analyses`;
 - Easy access to solvers in `zospy.solvers`;
 - Easy access to all API constants in `zospy.constants`;
-- Autocomplete for all ZOS-API endpoints and constants.
+- Autocomplete for all ZOS-API endpoints and constants;
+- Solves common problems related to Python.NET 3 and interaction with the ZOS-API. 
 
 ## Waranty and liability
 
 The code is provided as is, without any warranty. It is solely intended for research purposes. No warranty is given and
-no rights can be derived from it, as is also stated in the [GNU General Public License Version 3](LICENSE.txt).
+no rights can be derived from it, as is also stated in the [MIT license](LICENSE.txt).
 
 ## Installing
 
@@ -31,31 +35,30 @@ pip install zospy
 
 ## Dependencies
 
-ZOSPy officially supports Python 3.9 - 3.11. It may work with older Python versions, but support is not provided for
+ZOSPy officially supports Python 3.9 - 3.12. It may work with older Python versions, but support is not provided for
 these versions.
 
 ### Python packages
 
-- [Python for .NET](http://pythonnet.github.io/) 3.0.1
+- [Python for .NET](http://pythonnet.github.io/) 3.0.3
 - [pandas](https://pandas.pydata.org/)
 - [NumPy](https://numpy.org/)
+- [SemVer](https://python-semver.readthedocs.io/en/latest/index.html) 3.0.2
 
 ### Software
 
 - [Ansys Zemax OpticStudio](https://www.zemax.com/pages/opticstudio)
 
 ### Compatibility
 
-> :warning: Version 1.0.0 introduced some breaking changes. See
-> the [release notes](https://github.com/MREYE-LUMC/ZOSPy/releases/tag/v1.0.0) for more information.
-
 ZOSPy is tested with the following versions of Python and Ansys Zemax OpticStudio:
 
-| Zemax       | 20.3.2 | 23.0.1 | 23.2.1 |
-|-------------|--------|--------|--------|
-| Python 3.9  | ⚠      | ✔      | ✔      |
-| Python 3.10 | ⚠      | ✔      | ✔      |
-| Python 3.11 | ⚠      | ✔      | ✔      |
+| Zemax       | 20.3.2 | 23.1.0 | 23.2.1 | 24.1.0 |
+|-------------|--------|--------|--------|--------|
+| Python 3.9  | ⚠      | ✔      | ✔      | ✔      |
+| Python 3.10 | ⚠      | ✔      | ✔      | ✔      |
+| Python 3.11 | ⚠      | ✔      | ✔      | ✔      |
+| Python 3.12 | ⚠      |        |        | ✔      |
 
 ✔: This version works without problems.
 ⚠: This version works, but the output of analyses can differ slightly from the used reference version (currently **OpticStudio 23 R1.01**).
@@ -85,17 +88,14 @@ The connection as extension to running software OpticStudio is initiated as:
 import zospy as zp
 
 zos = zp.ZOS()
-zos.wakeup()
-zos.connect_as_extension()
-oss = zos.get_primary_system()
+oss = zos.connect("extension")
 ```
 
 Make sure that the OpticStudio software is set up to be connected to as extension through the API. Alternatively, a
-standalone OpticStudio application can be launched by changing the last two lines to:
+standalone OpticStudio application can be launched by changing the last line to:
 
 ```python
-zos.create_new_application()
-oss = zos.get_primary_system()
+oss = zos.connect("standalone")
 ```
 
 ### Using solvers
@@ -212,6 +212,6 @@ following implementation examples assume that `import logging` has been executed
 
 Feel free to contact us for any inquiries:
 
-- L. van Vught ([email](mailto:l.van_vught@lumc.nl))
-- J.W.M. Beenakker ([email](mailto:j.w.m.beenakker@lumc.nl))
 - C. Haasjes ([email](mailto:c.haasjes@lumc.nl))
+- J.W.M. Beenakker ([email](mailto:j.w.m.beenakker@lumc.nl))
+- L. van Vught ([email](mailto:l.van_vught@lumc.nl))
diff --git a/docs/advanced.md b/docs/advanced.md
@@ -0,0 +1,7 @@
+# Advanced usage
+
+```{toctree}
+:maxdepth: 1
+
+codecs
+```
diff --git a/docs/api.md b/docs/api.md
@@ -11,6 +11,7 @@
    zospy.zpcore
    zospy.analyses
    zospy.api.constants
+   zospy.api.codecs
    zospy.functions
    zospy.solvers
 ```