Merge pull request #153 from WISDEM/develop

v0.9.4

.github/workflows/ci-tests.yml

@@ -15,13 +15,13 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ["3.9", "3.10"]
+        python-version: ["3.9", "3.12"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 

.github/workflows/gh_pages.yml

@@ -8,12 +8,12 @@ jobs:
   make-pages:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.11'
 
       - name: Install dependencies
         run: |

.github/workflows/python-publish-test.yml

@@ -16,12 +16,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.11'
 
       - name: Build package
         run: |

.github/workflows/python-publish.yml

@@ -15,12 +15,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.11'
 
       - name: Build package
         run: |

.pre-commit-config.yaml

@@ -9,30 +9,30 @@ repos:
           stages: [commit]
 
 - repo: https://github.com/asottile/pyupgrade
-  rev: v3.15.0
+  rev: v3.15.2
   hooks:
   - id: pyupgrade
     args: [--py39-plus]
     stages: [commit]
 
 - repo: https://github.com/charliermarsh/ruff-pre-commit
-  rev: v0.1.8
+  rev: v0.4.2
   hooks:
   - id: ruff
     args: [--fix]
   - id: ruff-format
     types_or: [python, pyi, jupyter]
 
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: 'v1.7.1'  # Use the sha / tag you want to point at
+  rev: 'v1.10.0'  # Use the sha / tag you want to point at
   hooks:
   - id: mypy
     entry: mypy --install-types --non-interactive --config-file .mypy.ini
     exclude: (^docs/|^tests/)
     additional_dependencies: ["types-python-dateutil", "types-attrs", "types-PyYAML"]
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.5.0
+  rev: v4.6.0
   hooks:
   -   id: trailing-whitespace
   -   id: end-of-file-fixer

CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.9.4 (1 July 2024)
+
+- Adds support for Python 3.11 and 3.12.
+- Adds the following capability and servicing equipment codes:
+  - MCN for medium cranes, which should enable greater options for land-based wind.
+  - VSG for vessel support groups, or any representation of multiple vessels used for a
+    single operation.
+- Updates Polars API usage to account for a series of deprecation and future warnings.
+- Changes the metrics demonstration to use the COREWIND Morro Bay in situ example, and
+  adds the availability plotting to the demonstration example.
+- `RepairRequest.prior_operating_level` has been added to allow 100% reduction factor failures to correctly and consistently restore the operating level of a subassembly following a repair.
+- Replaces the `valid_reduction` attrs validator with `validate_0_1_inclusive` to reuse the logic in multiple places without duplicating checking methods.
+- Adds a `replacement` flag for interruption methods, so that a failure or replacement comment can be added as a cause for `simpy.process.interrupt`. This update allows the failure and maintenance processes to check if an interruption should cause the process to exit completely. Additionally, the forced exit ensures that processes can't persist after a replacement event when a process is recreated, which was happening in isolated cases.
+- Fixes a bug in `RepairManager.purge_subassemble_requests()` where the pending tows are cleared regardless of whether or not the focal subassembly is the cause of the tow, leading to a simulation failure.
+- Fixes a bug in `utilities/utilities.py:create_variable_from_string()` to operate in a way that is expected. The original method was removing all numerics, but only leading punctuation and numerics should be replaced, with any punctuation being replaced with an underscore.
+- Adds additional inline comments for clarification on internal methods.
+- Update README.md to be inline with current conda and Python standards.
+- Fully adopts `functools.cache` now that older Python versions where
+  `functools.lru_cache` was the available caching method.
+- Fixes a Pandas `FutureWarning` by removing a now unnecessary piece of code in
+  `wombat/core/post_processor.py:equipment_costs`
+
 ## v0.9.3 (15 February 2024)
 
 - Reinstate the original time-based availability methodology, which is based on all

README.md

@@ -2,6 +2,7 @@
 
 [![DOI 10.2172/1894867](https://img.shields.io/badge/DOI-10.2172%2F1894867-brightgreen?link=https://doi.org/10.2172/1894867)](https://www.osti.gov/biblio/1894867)
 [![PyPI version](https://badge.fury.io/py/wombat.svg)](https://badge.fury.io/py/wombat)
+[![codecov](https://codecov.io/gh/WISDEM/WOMBAT/branch/main/graph/badge.svg?token=SK9M10BZXY)](https://codecov.io/gh/WISDEM/WOMBAT)
 [![Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/WISDEM/WOMBAT/main?filepath=examples)
 [![Jupyter Book](https://jupyterbook.org/badge.svg)](https://wisdem.github.io/WOMBAT)
@@ -62,23 +63,7 @@ folder, but here are a few highlights:
 
 ### Requirements
 
-* Python 3.8 through 3.10
-
-> **Note**
-> For Python 3.10 users that seek to install more than the base dependencies, it has
-> been noted that pip may take a long time to resolve all of the package requirements,
-> so it is recommended to use the following workflow:
-
-```console
-# Enter the source code directory
-cd wombat/
-
-# First install the base package requirements
-pip install -e .
-
-# Then install whichever additional dependencies are required/desired
-pip install -e '.[dev]'  # '.[docs]' or '.[all]'
-```
+* Python 3.9 through 3.12
 
 ### Environment Setup
 
@@ -90,7 +75,7 @@ for the appropriate OS version.
 Using conda, create a new virtual environment:
 
 ```console
-conda create -n <environment_name> python=3.8 --no-default-packages
+conda create -n <environment_name> python=3.11
 conda activate <environment_name>
 conda install -c anaconda pip
 
@@ -103,15 +88,23 @@ conda deactivate
 
 ### Installation
 
+Once in your desired environment, WOMBAT can be installed from PyPI via `pip install`
+or from source.
 
 #### Pip
 
+This option is best for those working with the latest release, or including WOMBAT as
+a tool in a workflow without the desire to modify the source code.
+
 ```console
 pip install wombat
 ```
 
 #### From Source
 
+This option is ideal for users that wish to work with the examples, modify the source
+code, and/or contribute back to the project.
+
 Install it directly into an activated virtual environment:
 
 ```console
@@ -135,14 +128,15 @@ wombat.__version__
 
 For further usage, please see the documentation site at https://wisdem.github.io/WOMBAT.
 
-
 ### Requirements for Contributing to WOMBAT
 
 #### Code Contributions
 
 Code contributors should note that there is both an additional dependency suite for
-running the tests and enabling the pre-commit workflow to automically standardize the
-core code formatting principles.
+running the tests and enabling the pre-commit workflow to automatically standardize the
+core code formatting principles. In short, the following steps should be taken, but be
+sure to read the
+[contributor's guide](https://wisdem.github.io/WOMBAT/contributing.html)
 
 ```console
 git clone https://github.com/WISDEM/WOMBAT.git
@@ -169,7 +163,7 @@ Basic pre-commit issues that users might encounter and their remedies:
   applied changes. Once all checks pass, the commit is safe to be pushed.
 * `isort`, `black`, or simple file checks failed, but made changes
   * rerun the `add` and `commit` processes as needed until the changes satisfy the checks
-* `pylint` or `flake8` failed:
+* `ruff` failed:
   * Address the errors and rerun the `add` and `commit` processes
 * `mypy` has type errors that seem incorrect
   * Double check the typing is in fact as correct as it seems it should be and rerun the
@@ -193,8 +187,8 @@ Build the site
 
 > **Note**
 > You may want to change the "execute_notebooks" parameter in the `docs/_config.yaml`
-> file to "off" unless you're updating the coded examples or they will be run every time
-> you build the site.
+> file to "off" unless you're updating the coded examples, or they will be run every
+> time you build the site.
 
 ```console
 jupyter-book build docs
@@ -209,3 +203,45 @@ git clone https://github.com/WISDEM/WOMBAT.git
 cd wombat
 pip install -e '.[all]'
 ```
+
+### Dependencies
+
+Standard dependencies:
+
+* attrs>=21
+* numpy>=1.21
+* scipy>=1.8
+* pandas>=2
+* polars>=0.17
+* pyarrow>=10
+* jupyterlab>=3
+* simpy>=4.0.1
+* pyyaml>=6
+* geopy>=2.3
+* networkx>=2.7
+* matplotlib>=3.3
+* types-attrs>=19
+* types-typed-ast>=1.5
+* types-PyYAML>=6
+* types-python-dateutil>=2.8
+
+Optional "dev" dependencies:
+
+* pre-commit>=2.20
+* isort>=5.10
+* pytest>=7
+* pytest-cov>=4
+* mypy==0.991
+* ruff>=0.2
+* pyupgrade
+
+Optional "docs" dependencies:
+
+* jupyter-book>=0.15
+* myst-nb>=0.16
+* myst-parser>=0.17
+* linkify-it-py>=2
+* sphinx-autodoc-typehints
+* sphinxcontrib-autoyaml
+* sphinxcontrib-bibtex>=2.4
+* sphinxcontrib-spelling>=7

docs/API/utilities.md

@@ -1,5 +1,6 @@
 # Helpers and Plotting
 
+(plotting)=
 ## Plotting
 
 ```{eval-rst}

docs/examples/examples_reference.md

@@ -41,7 +41,7 @@ This is the notebook used for the NAWEA WindTech 2023 Workshop. See
 ### `dinwoodie_validation.ipynb`
 
 This shows the latest results of the model validation using the modeling parameters from
-Dinwoodie, et. al, 2015 [^dinwoodie2015reference].
+Dinwoodie, et al., 2015 [^dinwoodie2015reference].
 
 ### `iea_26_validation.ipynb`
 

docs/examples/how_to.md

@@ -11,9 +11,14 @@ kernelspec:
 
 # How To Use WOMBAT
 
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/WISDEM/WOMBAT/main?filepath=examples)
+
 This tutorial will walk through the setup, running, and results stages of a WOMBAT
 simulation while providing background information about how each component is related.
 
+A Jupyter notebook of this tutorial can be run from `examples/how_to.ipynb` locally, or
+through [binder](https://mybinder.org/v2/gh/WISDEM/WOMBAT/main?filepath=examples).
+
 ## Imports
 
 The following code block demonstrates a typical setup for working with WOMBAT and
@@ -261,6 +266,9 @@ CTV
 SCN
 : small crane (i.e., field support vessel or cherry picker)
 
+MCN
+: medium crane (i.e., anything between a cherry picker and a crawler crane)
+
 LCN
 : large crane (i.e., heavy lift vessel or crawler crane)
 
@@ -278,6 +286,10 @@ AHV
 : anchor handling vessel (this is a variation on the tugboat for mooring repairs that
 will not tow anything between port and site, but operate at the site)
 
+VSG
+: vessel support group (used as a means for modeling a grouping of vessels used for a
+sing repair operation)
+
 Aside from the TOW and AHV capabilities there are no operations specific to each
 capability. The remaining configurations of a servicing equipment such as equipment
 rates, mobilization, labor, and operating limits will define the nature of its operation