pywr 2.0.0.dev0__cp313-cp313t-win_amd64.whl

pywr/__init__.py

@@ -0,0 +1,61 @@
+from pathlib import Path
+from typing import Optional
+
+from .pywr import (
+    ModelSchema,
+    MultiNetworkModelSchema,
+    Model,
+    MultiNetworkModel,
+    ModelResult,
+    ModelTimings,
+    MultiNetworkModelTimings,
+    Timestep,
+    ScenarioIndex,
+    ParameterInfo,
+    Metric,
+    ComponentConversionError,
+    ConversionError,
+    convert_model_from_v1_json_string,
+    convert_metric_from_v1_json_string,
+)
+
+__all__ = [
+    "ModelSchema",
+    "MultiNetworkModelSchema",
+    "Model",
+    "MultiNetworkModel",
+    "ModelResult",
+    "ModelTimings",
+    "MultiNetworkModelTimings",
+    "Timestep",
+    "ScenarioIndex",
+    "ParameterInfo",
+    "Metric",
+    "ComponentConversionError",
+    "ConversionError",
+    "convert_model_from_v1_json_string",
+    "convert_metric_from_v1_json_string",
+    "run_from_path",
+]
+
+
+def run_from_path(
+    filename: Path,
+    data_path: Optional[Path] = None,
+    output_path: Optional[Path] = None,
+    solver: str = "clp",
+):
+    """Load and run a Pywr model from a file path.
+
+    If the `data_path` and `output_path` are not specified, they will be set to the
+    directory containing the model file.
+    """
+
+    if data_path is None:
+        data_path = filename.parent
+    if output_path is None:
+        output_path = filename.parent
+
+    schema = ModelSchema.from_path(filename)
+    model = schema.build(data_path=data_path, output_path=output_path)
+    model.run(solver)

pywr/__main__.py

@@ -0,0 +1,4 @@
+from .cli import start_cli
+
+if __name__ == "__main__":
+    start_cli()

pywr/cli.py

@@ -0,0 +1,48 @@
+import logging
+from pathlib import Path
+from typing import Optional
+
+import click
+from . import run_from_path
+
+
+def configure_logging():
+    logger = logging.getLogger("pywr")
+    logger.setLevel(logging.INFO)
+
+    ch = logging.StreamHandler()
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    ch.setFormatter(formatter)
+    logger.addHandler(ch)
+
+
+@click.group()
+def cli():
+    configure_logging()
+
+
+@cli.command()
+@click.argument("path", type=click.Path(exists=True, file_okay=True))
+@click.option("-s", "--solver", type=click.Choice(["clp", "highs"]), default="clp")
+@click.option(
+    "-d", "--data-path", type=click.Path(exists=True, dir_okay=True), default=None
+)
+@click.option(
+    "-o", "--output-path", type=click.Path(exists=True, dir_okay=True), default=None
+)
+def run(path: str, solver: str, data_path: Optional[str], output_path: Optional[str]):
+    data_path = Path(data_path) if data_path is not None else None
+    output_path = Path(output_path) if output_path is not None else None
+
+    run_from_path(
+        Path(path),
+        solver=solver,
+        data_path=data_path,
+        output_path=output_path,
+    )
+
+
+def start_cli():
+    cli()

pywr/pywr.pyi

@@ -0,0 +1,241 @@
+from datetime import datetime
+from os import PathLike
+from typing import Optional, List
+import polars as pl
+
+class ParameterInfo:
+    """Provides data for a custom Pywr parameter.
+
+    This is a read-only object that provides information that can be used for custom parameters in Pywr. It
+    is passed as the first argument to the `calc` and `after` methods of custom parameter objects.
+    """
+
+    @property
+    def timestep(self) -> "Timestep":
+        """Returns the current time-step object."""
+
+    @property
+    def scenario_index(self) -> "ScenarioIndex":
+        """Returns the current scenario index object."""
+
+    def get_metric(self, name: str) -> float:
+        """Returns a metric by name.
+
+        Args:
+            name: The name of the metric to retrieve.
+        """
+
+    def get_index(self, name: str) -> int:
+        """Returns the index of a component by name.
+
+        Args:
+            name: The name of the component to retrieve the index for.
+        """
+
+class Timestep:
+    """Represents a single time-step in a simulation.
+
+    This is a read-only object that provides information about the current time-step.
+    """
+
+    @property
+    def is_first(self) -> bool:
+        """Returns true if this is the first time-step."""
+
+    @property
+    def days(self) -> float:
+        """Returns the duration of the time-step in number of days including any fractional part."""
+
+    @property
+    def date(self) -> datetime:
+        """Returns the date of the time-step."""
+
+    @property
+    def day(self) -> int:
+        """Returns the day of the time-step."""
+
+    @property
+    def month(self) -> int:
+        """Returns the month of the time-step."""
+
+    @property
+    def year(self) -> int:
+        """Returns the year of the time-step."""
+
+    @property
+    def index(self) -> int:
+        """Returns the current time-step index."""
+
+    @property
+    def day_of_year(self) -> int:
+        """Returns the day of the year index of the timestep.
+
+        The day of the year is one-based, meaning January 1st is day 1 and December 31st is day 365 (or 366 in leap years).
+        """
+
+    @property
+    def day_of_year_index(self) -> int:
+        """Returns the day of the year index of the timestep.
+
+        The index is zero-based and accounts for leaps days. In non-leap years, 1 i to the index for
+        days after Feb 28th.
+        """
+
+    @property
+    def fractional_day_of_year(self) -> float:
+        """Returns the fraction day of the year of the timestep.
+
+        The index is zero-based and accounts for leaps days. In non-leap years, 1 is added to the index for
+        days after Feb 28th. The fractional part is the fraction of the day that has passed since midnight
+        (calculated to the nearest second).
+        """
+
+    @property
+    def is_leap_year(self) -> bool:
+        """Returns true if the year of the timestep is a leap year."""
+
+class ScenarioIndex:
+    """Represents a scenario index in a Pywr model.
+
+    This is a read-only object that provides information about the current scenario index.
+    """
+
+    @property
+    def simulation_id(self) -> int:
+        """Returns the current simulation id."""
+
+    @property
+    def simulation_indices(self) -> List[int]:
+        """Returns indices for each scenario group for this simulation."""
+
+class ModelSchema:
+    @classmethod
+    def from_path(cls, path: PathLike) -> "ModelSchema":
+        """Create a new schema object from a file path.
+
+        Args:
+            path: The path to the schema JSON file.
+        """
+
+    @classmethod
+    def from_json_string(cls, json_string: str) -> "ModelSchema":
+        """Create a new schema object from a JSON string.
+
+        Args:
+            json_string: The JSON string representing the schema.
+        """
+
+    def to_json_string(self) -> str:
+        """Serialize the schema to a JSON string."""
+
+    def build(
+        self, data_path: Optional[PathLike], output_path: Optional[PathLike]
+    ) -> "Model":
+        """Build the schema in to a Pywr model."""
+
+class MultiNetworkModelSchema:
+    @classmethod
+    def from_path(cls, path: PathLike) -> "ModelSchema":
+        """Create a new schema object from a file path.
+
+        Args:
+            path: The path to the schema JSON file.
+        """
+
+    @classmethod
+    def from_json_string(cls, json_string: str) -> "ModelSchema":
+        """Create a new schema object from a JSON string.
+
+        Args:
+            json_string: The JSON string representing the schema.
+        """
+
+    def to_json_string(self) -> str:
+        """Serialize the schema to a JSON string."""
+
+    def build(
+        self, data_path: Optional[PathLike], output_path: Optional[PathLike]
+    ) -> "Model":
+        """Build the schema in to a Pywr model."""
+
+class Model:
+    def run(self, solver_name: str, solver_kwargs: Optional[dict] = None):
+        """Run the model using the specified solver.
+
+        Args:
+            solver_name: The name of the solver to use.
+            solver_kwargs: Optional keyword arguments to pass to the solver.
+        """
+
+class MultiNetworkModel:
+    def run(self, solver_name: str, solver_kwargs: Optional[dict] = None):
+        """Run the model using the specified solver.
+
+        Args:
+            solver_name: The name of the solver to use.
+            solver_kwargs: Optional keyword arguments to pass to the solver.
+        """
+
+class ModelResult:
+    @property
+    def network_result(self) -> "NetworkResult":
+        """Returns the network result object."""
+
+    @property
+    def timings(self) -> "ModelTimings":
+        """Returns the model timings object."""
+
+class MultiNetworkModelResult:
+    def network_results(self, name: str) -> "NetworkResult":
+        """Get the network result for a specific network by name.
+
+        Args:
+            name: The name of the network to retrieve the results for.
+        """
+
+    @property
+    def timings(self) -> "MultiNetworkModelTimings":
+        """Returns the model timings object."""
+
+class NetworkResult:
+    def aggregated_value(self, name: str) -> float:
+        """Get the aggregated value of a recorder by name, if it exists and can be aggregated.
+
+        Args:
+            name: The name of the output to retrieve.
+        """
+
+    def to_dataframe(self, name: str) -> pl.DataFrame:
+        """Get the output of a recorder by name as a polars DataFrame.
+
+        Args:
+            name: The name of the output to retrieve.
+        """
+
+    def output_names(self) -> list[str]:
+        """Get a list of all available output names."""
+
+class ModelTimings:
+    @property
+    def total_duration(self) -> float:
+        """Total duration of the model run in seconds."""
+
+    @property
+    def speed(self) -> float:
+        """Model speed in timesteps per second."""
+
+class MultiNetworkModelTimings:
+    @property
+    def total_duration(self) -> float:
+        """Total duration of the model run in seconds."""
+
+    @property
+    def speed(self) -> float:
+        """Model speed in timesteps per second."""
+
+class Metric: ...
+class ComponentConversionError: ...
+class ConversionError: ...
+
+def convert_model_from_v1_json_string(data: str): ...
+def convert_metric_from_v1_json_string(data: str): ...

pywr-2.0.0.dev0.dist-info/METADATA

@@ -0,0 +1,349 @@
+Metadata-Version: 2.4
+Name: pywr
+Version: 2.0.0.dev0
+Requires-Dist: pandas
+Requires-Dist: polars>=1.32
+Requires-Dist: pyarrow
+Requires-Dist: click
+Requires-Dist: openpyxl ; extra == 'excel'
+Requires-Dist: h5py ; extra == 'hdf'
+Provides-Extra: excel
+Provides-Extra: hdf
+License-File: LICENSE
+Summary: 
+Author-email: James Tomlinson <tomo.bbe@gmail.com>
+License-Expression: MIT OR Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+<!-- PROJECT SHIELDS -->
+<!--
+*** I'm using markdown "reference style" links for readability.
+*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
+*** See the bottom of this document for the declaration of the reference variables
+*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
+*** https://www.markdownguide.org/basic-syntax/#reference-style-links
+-->
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![MIT License][license-shield]][license-url]
+[![LinkedIn][linkedin-shield]][linkedin-url]
+
+
+<!-- PROJECT LOGO -->
+<br />
+<div align="center">
+
+<!--
+***  <a href="https://github.com/pywr/pywr-next">
+***    <img src="images/logo.png" alt="Logo" width="80" height="80">
+***  </a>
+-->
+
+<h3 align="center">Pywr-next</h3>
+
+  <p align="center">
+    This is repository contains the current work-in-progress for the next major revision to
+    <a href="https://github.com/pywr/pywr">Pywr.</a> It uses Rust as a backend instead of Cython. It
+    is currently not ready for use beyond development and experimentation. Comments and discussions are welcome.
+    <br />
+    <br />
+    <a href="https://pywr.github.io/pywr-next/">User Guide</a>
+    ·
+    <a href="https://github.com/pywr/pywr-next/issues">Report Bug</a>
+    ·
+    <a href="https://github.com/pywr/pywr-next/issues">Request Feature</a>
+  </p>
+</div>
+
+
+
+<!-- TABLE OF CONTENTS -->
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+      <ul>
+        <li><a href="#built-with">Built With</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#roadmap">Roadmap</a></li>
+    <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#license">License</a></li>
+    <li><a href="#contact">Contact</a></li>
+    <li><a href="#acknowledgments">Acknowledgments</a></li>
+  </ol>
+</details>
+
+
+
+<!-- ABOUT THE PROJECT -->
+
+## About The Project
+
+Pywr-1.x is a Python library which utilises Cython for performance. Over time this has resulted in a "core"
+set of data structures and objects that are written in Cython to gain maximum performance. Cython has the nice
+benefit of making it easy to extend that core functionality using regular Python. However, the border between what
+is Python and what is Cython is a bit blurred and not well designed in certain places.
+
+One option for the future development of Pywr (e.g. Pywr-2.x) would be a more explicit separation between the compute
+"core" and higher level functionality. Rust is a candidate for writing that core largely independent of Python, and
+possibly offers the benefits of (1) greater performance than Cython, and (2) easier maintenance in the future.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+### Requirements
+
+Any major revision to Pywr will have the following feature requirements:
+
+- Retain the "Parameter" system from Pywr-1.x - this is core functionality that makes Pywr really flexible.
+- Extendable in Python space.
+- An improved approach for outputting data and metrics.
+- Better error handling.
+- Cross-platform.
+- Faster!
+- Strong input file (JSON) schema.
+
+### Built With
+
+[![Rust][Rust]][Rust-url]
+[![Python][Python]][Python-url]
+
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- GETTING STARTED -->
+
+### Getting started
+
+This repository contains a version of Clp using Git submodules. In order to build those submodules
+must be initialised first.
+
+```bash
+git submodule init
+git submodule update
+```
+
+Rust is required for installation of the Python extension. To create a Python development installation
+requires first compiling the Rust library and then the Python extension. The following example uses
+a virtual environment to install the Python dependencies, compile the Pywr extension and run the Pywr Python CLI.
+
+```bash
+python -m venv .venv # create a new virtual environment
+source .venv/bin/activate # activate the virtual environment (linux)
+# .venv\Scripts\activate # activate the virtual environment (windows)
+pip install maturin  # install maturin for building the Python extension
+maturin develop # compile the Pywr Python extension
+python -m pywr  # run the Pywr Python CLI
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- USAGE EXAMPLES -->
+
+## Usage
+
+### Rust CLI
+
+A basic command line interface is included such that you can use this version of Pywr without Python.
+This CLI is in the `pywr-cli` crate.
+
+To see the CLI commands available run the following:
+
+```bash
+cargo run -p pywr-cli -- --help
+```
+
+To run a Pywr v2 model use the following:
+
+```bash
+cargo run -p pywr-cli -- run tests/models/simple1.json
+```
+
+### Python CLI
+
+If the Python extension has been compiled using the above instructions a model can be run using the basic Python
+CLI.
+
+```bash
+python -m pywr run tests/models/simple1.json
+```
+
+## Porting a Pywr v1.x model to v2.x
+
+This version of Pywr is not backward compatible with Pywr v1.x. One of the major reasons for this version is the
+lack of a strong schema in the Pywr v1.x JSON files. Pywr v2.x uses an updated JSON schema that is defined in this
+repository. Therefore, v1.x JSON files must be converted to the v2.x JSON schema. This conversion can be undertaken
+manually, but there is also a work-in-progress conversion tool. The conversion tool uses a v1.x schema defined in
+the [pywr-schema](https://github.com/pywr/pywr-schema) project.
+
+**Please note that conversion from Pywr v1.x to v2.x is experimental and not all features of Pywr are implemented
+in `pywr-schema` or have been implemented in Pywr v2.x yet. Due to the changes between these versions it is very
+likely an automatic conversion will not completely convert your model, and it _WILL_ require manual testing and
+checking.**
+
+```bash
+cargo run --no-default-features -- convert /path/to/my/v1.x/model.json
+```
+
+Feedback on porting models is very welcome, so please open an issue with any questions or problems.
+
+
+<!-- _For more examples, please refer to the [Documentation](https://example.com)_ -->
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- CRATES -->
+
+## Crates
+
+This repository contains the following crates:
+
+### Pywr-core
+
+A low-level Rust library for constructing network models. This crate interfaces with linear program solvers.
+
+Feature flags:
+
+| Feature    | Description                                      | Default |
+|------------|--------------------------------------------------|---------|
+| `pyo3`     | Enable the Python bindings.                      | True    |
+| `highs`    | Enable the HiGHS LP solver.                      | False   |
+| `ipm-ocl`  | Enable the OpenCL IPM solver (requires nightly). | False   |
+| `ipm-simd` | Enable the AVX IPM solver (requires nightly).    | False   |
+| `cbc`      | Enable the CBC MILP solver.                      | False   |
+
+### Pywr-schema
+
+A Rust library for validating Pywr JSON files against a schema, and then building a model from the schema
+using `pywr-core`.
+
+Feature flags:
+
+| Feature    | Description                                                                                                                                                                                                                                          | Default |
+|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| `core`     | Enable building models from the schema with `pywr-core`. This feature is enabled by default, but requires a lot of dependencies. If you only require schema validation and manipulation consider building this crate with `default-features = false` | True    |
+| `pyo3`     | Enable the Python bindings.                                                                                                                                                                                                                          | True    |
+| `highs`    | Enable the HiGHS LP solver.                                                                                                                                                                                                                          | False   |
+| `ipm-ocl`  | Enable the OpenCL IPM solver (requires nightly).                                                                                                                                                                                                     | False   |
+| `ipm-simd` | Enable the AVX IPM solver (requires nightly).                                                                                                                                                                                                        | False   |
+| `cbc`      | Enable the CBC MILP solver.                                                                                                                                                                                                                          | False   |
+
+### Pywr-cli
+
+A command line interface for running Pywr models.
+
+### Pywr-python
+
+A Python extension (and package) for constructing and running Pywr models.
+
+
+<!-- ROADMAP -->
+
+## Roadmap
+
+- [x] Proof-of-concept - demonstrate the benefits of the RIIR approach.
+- [ ] Redesign of outputs & metrics.
+- [ ] Redesign of variable API for integration with external optimisation algorithms.
+- [ ] Implement outstanding `Parameters` from Pywr v1.x
+- [ ] Design & implement Python API using Rust extension.
+- [ ] Release Pywr v2.x beta
+
+See the [open issues](https://github.com/pywr/pywr-next/issues) for a full list of proposed features (and known issues).
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- CONTRIBUTING -->
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any
+contributions you make are **greatly appreciated**.
+
+If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also
+simply open an issue with the tag "enhancement".
+Don't forget to give the project a star! Thanks again!
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+<!-- LICENSE -->
+
+## License
+
+Distributed under the Apache 2.0 or MIT License. See `LICENSE.txt` for more information.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- CONTACT -->
+
+## Contact
+
+James Tomlinson - tomo.bbe@gmail.com
+
+Project Link: [https://github.com/pywr/pywr-next](https://github.com/pywr/pywr-next)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- MARKDOWN LINKS & IMAGES -->
+<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
+
+[contributors-shield]: https://img.shields.io/github/contributors/pywr/pywr-next.svg?style=for-the-badge
+
+[contributors-url]: https://github.com/pywr/pywr-next/graphs/contributors
+
+[forks-shield]: https://img.shields.io/github/forks/pywr/pywr-next.svg?style=for-the-badge
+
+[forks-url]: https://github.com/pywr/pywr-next/network/members
+
+[stars-shield]: https://img.shields.io/github/stars/pywr/pywr-next.svg?style=for-the-badge
+
+[stars-url]: https://github.com/pywr/pywr-next/stargazers
+
+[issues-shield]: https://img.shields.io/github/issues/pywr/pywr-next.svg?style=for-the-badge
+
+[issues-url]: https://github.com/pywr/pywr-next/issues
+
+[license-shield]: https://img.shields.io/github/license/pywr/pywr-next.svg?style=for-the-badge
+
+[license-url]: https://github.com/pywr/pywr-next/blob/main/LICENSE
+
+[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
+
+[linkedin-url]: https://linkedin.com/in/james-tomlinson-a465352b
+
+[Rust]: https://img.shields.io/badge/rust-ef4a23?style=for-the-badge&logo=rust&logoColor=white
+
+[Rust-url]: https://www.rust-lang.org/
+
+[Python]: https://img.shields.io/badge/python-275277?style=for-the-badge&logo=python&logoColor=white
+
+[Python-url]: https://www.python.org/
+
+Copyright (C) 2020-2023 James Tomlinson Associates Ltd.
+

pywr-2.0.0.dev0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pywr-2.0.0.dev0.dist-info/METADATA,sha256=shZcotSIr-tYWvrcHW09pBKn09Fy4oDjzJJX5wX8RdM,13649
+pywr-2.0.0.dev0.dist-info/WHEEL,sha256=NIX3GH-EI7FzrKEcrM4JPmD21jlBdrrjPRxjD1D-qeI,97
+pywr-2.0.0.dev0.dist-info/licenses/LICENSE,sha256=XYeBp8D-A_-e_GzJ2d-EsvNuHlhbTrDILJfREAPjoiI,1093
+pywr/__init__.py,sha256=fLZHVN_moM7tZULdZCERwb9ThoV1QDyLTUXlUg4FWmc,1481
+pywr/__main__.py,sha256=xkoHzRjxKvsW91lMdPz9ahq91_ZgcL78iJO54j6wNfQ,75
+pywr/cli.py,sha256=nfrM_DWZP3TBDeUsS6gTyJ0cUHvRP-JEtuVdXXmgXT8,1265
+pywr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pywr/pywr.cp313t-win_amd64.pyd,sha256=mryUdoHefTJqlIHa2BRpBl5vY4L4B79gupYWQtTICcU,79547904
+pywr/pywr.pyi,sha256=lQOdA8ROqM6corA6YyFcfjD-F0N1KczY6zjrLfIvX2I,7430
+pywr-2.0.0.dev0.dist-info/RECORD,,

pywr-2.0.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.4)
+Root-Is-Purelib: false
+Tag: cp313-cp313t-win_amd64

pywr-2.0.0.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 James Tomlinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.