libcosimpy update - Ecco algorithm, conan update, type checking etc. (#15)

Update to libcosimpy for supporting ecco algorithm.

- Using the latest libcosim/libcosimc
- Ecco API
- Using conan v2
- Added type checking

Author: davidhjp01

.github/workflows/ci-main.yml

@@ -4,36 +4,37 @@ name: libcosimpy CI
 on: [push, workflow_dispatch]
 
 jobs:
-  test:
-    name: Tests
-    runs-on: ${{ matrix.platform }}
-    strategy:
-      fail-fast: false
-      matrix:
-        platform: [ 'windows-latest', 'ubuntu-latest' ]
-        python-version: [ '3.8', '3.9', '3.10', '3.11', '3.12' ]
+  code_quality:
+    name: Code Quality
+    runs-on: 'ubuntu-latest'
     timeout-minutes: 35
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
-      - name: 'Run test'
-        run: |
-          pip install .
-          pip install pytest==7.2.2
-          pytest .
+          python-version-file: 'pyproject.toml'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Install dependencies
+        run: uv sync --no-install-project
+      - name: Run ruff format
+        run: uv run --no-project ruff format --diff
+      - name: Run ruff check
+        run: uv run --no-project ruff check --diff
+      - name: Run pyright
+        run: uv run --no-project pyright
 
-  build_wheels:
-    name: Build wheels
-    needs:
-      - test
+  build_wheels_and_test:
+    name: Build / Test
     runs-on: ${{ matrix.platform }}
     strategy:
       fail-fast: false
       matrix:
         platform: [ 'windows-latest', 'ubuntu-latest' ]
-        python-version: [ 'cp38', 'cp39', 'cp310', 'cp311', 'cp312' ]
+        python-version: [ 'cp310', 'cp311', 'cp312', 'cp313' ]
     timeout-minutes: 35
     env:
       CONAN_REVISIONS_ENABLED: 1
@@ -42,10 +43,20 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.11
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.19.2
+        uses: pypa/cibuildwheel@v2.23.3
         env:
           CIBW_BUILD: "${{ matrix.python-version }}-win_amd64 ${{ matrix.python-version }}-manylinux_x86_64"
+          CIBW_BUILD_FRONTEND: build[uv]
+          CIBW_ENVIRONMENT: >
+            CONAN_UPLOAD_OSP=1
+            CONAN_LOGIN_USERNAME_OSP=${{ secrets.osp_artifactory_usr }}
+            CONAN_PASSWORD_OSP=${{ secrets.osp_artifactory_pwd }}
       - name: Twine check
         run: | 
            pip install twine
@@ -58,14 +69,15 @@ jobs:
           path: ./wheelhouse/*.whl
 
   build_source:
-    name: Build source
-    needs:
-      - test
+    name: Package source
     runs-on: 'ubuntu-latest'
     steps:
       - uses: actions/checkout@v3
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
       - name: Build source
-        run: | 
+        run: |
           pip install build twine
           python -m build --sdist
           twine check --strict ./dist/*
@@ -79,7 +91,8 @@ jobs:
   publish:
    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
    needs:
-     - build_wheels
+     - code_quality
+     - build_wheels_and_test
      - build_source
    runs-on: ubuntu-latest
    steps:
@@ -88,7 +101,7 @@ jobs:
          pattern: "*-wheel"
          merge-multiple: true
          path: ./dist/
-     - uses: pypa/gh-action-pypi-publish@v1.9.0
+     - uses: pypa/gh-action-pypi-publish@release/v1
        with:
          user: __token__
          password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -285,4 +285,8 @@ poetry.toml
 # LSP config files
 pyrightconfig.json
 
+# Custom
+/wheelhouse
+/graph.json
+
 # End of https://www.toptal.com/developers/gitignore/api/pycharm,python

README.md

@@ -149,6 +149,110 @@ execution.step()
 
 Scenario manipulators are also supported
 
+# Using ECCO algorithm
+
+Libcosimpy supports ECCO (Energy-Conservation-based Co-Simulation) algorithm based on the work in [1] for adaptively
+updating the step size of the simulation. The algorithm uses the law of conservation of energy between FMU models that
+represent power bonds from bond graph theory. 
+
+## Creating ECCO algorithm manually
+The parameters of the algorithm can be specified via the `EccoParam` class:
+
+```python
+params = EccoParams(
+    safety_factor=0.8,
+    step_size=1e-4,
+    min_step_size=1e-4,
+    max_step_size=0.01,
+    min_change_rate=0.2,
+    max_change_rate=1.5,
+    abs_tolerance=1e-4,
+    rel_tolerance=1e-4,
+    p_gain=0.2,
+    i_gain=0.15,
+)
+```
+
+The algorithm be created via `create_ecco_algorithm`, which can be used to create a new execution instance:
+
+```python
+# Create an algorithm instance
+ecco_algorithm = CosimAlgorithm.create_ecco_algorithm(params)
+
+# Create execution
+execution = CosimExecution.from_algorithm(ecco_algorithm)
+```
+
+The power bond between models is represented by input and output connection pair between two models:
+
+```python
+# Indicating a power bond between models (indicated by index chassis_index and wheel_index)
+ecco_algorithm.add_power_bond(
+    chassis_index,
+    chassis_v_out,
+    chassis_f_in,
+    wheel_index,
+    wheel_f_out,
+    wheel_v_in,
+)
+```
+
+The simulation is started as usual via `simulate_until` function from `CosimExecution`:
+```python
+execution.simulate_until(target_time=10e9)
+```
+
+See [test_ecco_algorithm](tests/test_ecco_algorithm.py) for detailed usage of ECCO algorithm.
+
+## Creating ECCO algorithm via system structure file
+
+Alternatively, ECCO algorithm can also be created via system structure file:
+```xml
+<OspSystemStructure xmlns="http://opensimulationplatform.com/MSMI/OSPSystemStructure" version="0.1">
+    ...
+    <!-- Specify ecco algorithm -->
+    <Algorithm>ecco</Algorithm>
+    ...
+    <Connections>
+        <!-- Annotate variable connection as power bond via `powerBond` attribute. Specify
+             causality of the variable (input or output) -->
+        <VariableConnection powerBond="wheelchassis">
+            <Variable simulator="chassis" name="velocity" causality="output"/>
+            <Variable simulator="wheel" name="in_vel" causality="input"/>
+        </VariableConnection>
+        <VariableConnection powerBond="wheelchassis">
+            <Variable simulator="wheel" name="out_spring_damper_f" causality="output"/>
+            <Variable simulator="chassis" name="force" causality="input"/>
+        </VariableConnection>
+    </Connections>
+    <!-- Specify ecco algorithm parameters -->
+    <EccoConfiguration>
+        <SafetyFactor>0.99</SafetyFactor>
+        <StepSize>0.0001</StepSize>
+        <MinimumStepSize>0.00001</MinimumStepSize>
+        <MaximumStepSize>0.01</MaximumStepSize>
+        <MinimumChangeRate>0.2</MinimumChangeRate>
+        <MaximumChangeRate>1.5</MaximumChangeRate>
+        <ProportionalGain>0.2</ProportionalGain>
+        <IntegralGain>0.15</IntegralGain>
+        <RelativeTolerance>1e-6</RelativeTolerance>
+        <AbsoluteTolerance>1e-6</AbsoluteTolerance>
+    </EccoConfiguration>
+</OspSystemStructure>
+```
+
+Then this file can be loaded via a usual way via `CosimExecution.from_osp_config_file`:
+```python
+execution = CosimExecution.from_osp_config_file(osp_path="tests/data/fmi2/quarter_truck")
+```
+
+See [Quarter truck example](tests/data/fmi2/quarter_truck/OspSystemStructure.xml) for detailed usage of ECCO algorithm via system structure file.
+
+
+## Reference
+[1] Sadjina, S. and Pedersen, E., 2020. Energy conservation and coupling error reduction in non-iterative co-simulations. Engineering with Computers, 36, pp.1579-1587.
+
+
 # Tests
 
 Tests can be run using the `pytest` command in the terminal. `libcosimc` log level for all tests can be set in the `./tests/conftest.py` file.