diff --git a/.buildinfo b/.buildinfo new file mode 100644 index 00000000..ae43dd0b --- /dev/null +++ b/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 49744bb105ad9761e5d9b30444d9216c +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/CHANGELOG.html b/CHANGELOG.html new file mode 100644 index 00000000..94db1fb3 --- /dev/null +++ b/CHANGELOG.html @@ -0,0 +1,1178 @@ + + + + + + + + + Changelog - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Changelog

+

All notable changes to the farn project will be documented in this file.
+The changelog format is based on Keep a Changelog.

+
+

Unreleased

+

-/-

+
+
+

[0.4.0] - 2024-11-11

+
+

Breaking changes

+
    +

  • The code has been adapted to dictIO 0.4.0
    +dictIO 0.4.0 introduced some breaking changes. With the current release 0.4.0 of farn, the code base has been adapted to these in changes.
    +The most prominent change being that class dictIO.CppDict has been replaced by class dictIO.SDict.

    • +
+
+
+

Changed

+
    +

  • Changed from pip/tox to uv as package manager

    • +

  • README.md : Completely rewrote section “Development Setup”, introducing uv as package manager.

    • +

  • Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI

    • +

  • Updated copyright statement

    • +

  • VS Code settings: Turned off automatic venv activation

    • +

  • Replaced black formatter with ruff formatter

    • +
+
+
+

Solved

+
    +

  • Sphinx documentation: Resolved issue that documentation of class members was generated twice.

    • +
+
+
+

Added

+
    +

  • Sphinx documentation: Added extension to support Markdown-based diagrams created with Mermaid.

    • +

  • Added mypy as static type checker (in addition to pyright)

    • +
+
+
+

GitHub workflows

+
    +

  • (all workflows): Adapted to use uv as package manager

    • +

  • _test_future.yml : updated Python version to 3.13.0-alpha - 3.13.0

    • +

  • _test_future.yml : updated name of test job to ‘test313’

    • +
+
+
+

Dependencies

+
    +

  • Updated to dictIO>=0.4.0 (from dictIO>=0.3.4)

    • +

  • Updated to ospx>=0.3.0 (from ospx>=0.2.14)

    • +

  • Updated to ruff>=0.6.3 (from ruff==0.4.2)

    • +

  • Updated to pyright>=1.1.378 (from pyright==1.1.360)

    • +

  • Updated to sourcery>=1.22 (from sourcery==1.16)

    • +

  • Updated to pytest>=8.3 (from pytest>=8.2)

    • +

  • Updated to Sphinx>=8.0 (from Sphinx>=7.3)

    • +

  • Updated to sphinx-argparse-cli>=1.17 (from sphinx-argparse-cli>=1.16)

    • +

  • Updated to myst-parser>=4.0 (from myst-parser>=3.0)

    • +

  • Updated to furo>=2024.8 (from furo>=2024.5)

    • +

  • updated to setup-python@v5 (from setup-python@v4)

    • +

  • updated to actions-gh-pages@v4 (from actions-gh-pages@v3)

    • +

  • updated to upload-artifact@v4 (from upload-artifact@v3)

    • +

  • Updated to download-artifact@v4 (from download-artifact@v3)

    • +

  • updated to checkout@v4 (from checkout@v3)

    • +
+
+
+
+

0.3.7 - 2024-05-22

+
+

Dependencies

+
    +

  • updated to ruff==0.4.2 (from ruff==0.2.1)

    • +

  • updated to pyright==1.1.360 (from pyright==1.1.350)

    • +

  • updated to sourcery==1.16 (from sourcery==1.15)

    • +

  • updated to lxml>=5.2 (from lxml>=5.1)

    • +

  • updated to types-lxml>=2024.4 (from types-lxml>=5.1)

    • +

  • updated to scipy>=1.13 (from scipy>=1.12)

    • +

  • updated to Pillow>=10.3 (from Pillow>=10.2)

    • +

  • updated to pytest>=8.2 (from pytest>=7.4)

    • +

  • updated to pytest-cov>=5.0 (from pytest-cov>=4.1)

    • +

  • updated to Sphinx>=7.3 (from Sphinx>=7.2)

    • +

  • updated to sphinx-argparse-cli>=1.15 (from sphinx-argparse-cli>=1.11)

    • +

  • updated to myst-parser>=3.0 (from myst-parser>=2.0)

    • +

  • updated to furo>=2024.4 (from furo>=2023.9.10)

    • +

  • updated to dictIO>=0.3.4 (from dictIO>=0.3.3)

    • +

  • updated to ospx>=0.2.14 (from ospx>=0.2.13)

    • +

  • updated to numpy>=1.26,<2.0 (from numpy>=1.26)

    • +

  • updated to matplotlib>=3.9 (from matplotlib>=3.8)

    • +

  • removed black

    • +
+
+
+

Changed

+
    +

  • replaced black formatter with ruff formatter

    • +

  • Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI

    • +

  • Updated copyright statement

    • +

  • VS Code settings: Turned off automatic venv activation

    • +
+
+
+

Added

+
    +

  • farn.core.case.Case: Added method add_parameters(), which allows to manually add user-defined parameters to a Case.

    • +
+
+
+
+

0.3.6 - 2024-02-21

+
+

Added

+
    +

  • README.md : Under Development Setup, added a step to install current package in “editable” mode, using the pip install -e option. +This removes the need to manually add /src to the PythonPath environment variable in order for debugging and tests to work.

    • +
+
+
+

Removed

+
    +

  • VS Code settings: Removed the setting which added the /src folder to PythonPath. This is no longer necessary. Installing the project itself as a package in “editable” mode, using the pip install -e option, solves the issue and removes the need to manually add /src to the PythonPath environment variable.

    • +
+
+
+

Changed

+
    +

  • Moved all project configuration from setup.cfg to pyproject.toml

    • +

  • Moved all tox configuration from setup.cfg to tox.ini.

    • +

  • Moved pytest configuration from pyproject.toml to pytest.ini

    • +

  • Deleted setup.cfg

    • +
+
+
+

Dependencies

+
    +

  • updated to black[jupyter]==24.1 (from black[jupyter]==23.12)

    • +

  • updated to version: ‘==24.1’ (from version: ‘==23.12’)

    • +

  • updated to ruff==0.2.1 (from ruff==0.1.8)

    • +

  • updated to pyright==1.1.350 (from pyright==1.1.338)

    • +

  • updated to sourcery==1.15 (from sourcery==1.14)

    • +

  • updated to lxml>=5.1 (from lxml>=4.9)

    • +

  • updated to scipy>=1.12 (from scipy>=1.11)

    • +

  • updated to pandas>=2.2 (from pandas>=2.1)

    • +

  • updated to Pillow>=10.2 (from Pillow>=10.1)

    • +

  • -/-

    • +
+
+
+
+

0.3.5 - 2024-01-09

+
+

Changed

+
    +

  • farn/sampling/sampling.py:

    +
      +

    • _generate_values_using_uniform_lhs_sampling(): +replaced SALib latin with pyDOE2 lhs

      • +

    • _generate_values_using_sobol_sampling(): +replaced sobol-seq with scipy.stats.qmc.sobol

      • +

    • removed orphaned _cov argument from normalLhs sampling

      • +
    +
    • +
+
+
+

Dependencies

+
    +

  • Upgraded from pyDOE2>=1.3 to pyDOE3>=1.0

    • +

  • Removed SALib and sobol-seq

    • +

  • Updated to dictIO>=0.3.1 and ospx>=0.2.12

    • +

  • Updated other dependencies to latest versions

    • +
+
+
+
+

0.3.4 - 2023-09-25

+
+

Dependencies

+
    +

  • Updated dependencies to latest versions

    • +
+
+
+
+

0.3.3 - 2023-06-22

+
+

Changed

+
    +

  • Modularized GitHub workflows

    • +

  • Changed default Python version in GitHub workflows from 3.10 to 3.11

    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.8 and ospx>=0.2.10

    • +

  • requirements-dev.txt: Updated dependencies to latest versions

    • +
+
+
+
+

0.3.2 - 2023-05-04

+
+

Changed

+
    +

  • dependencies: updated dependencies to latest versions

    • +
+
+
+
+

0.3.1 - 2023-01-11

+
+

Changed

+
    +

  • Added missing DocStrings for public classes, methods and functions

    • +

  • Changed links to package documentation to open README.html, not the default index page

    • +

  • data classes: changed initialisation of mutable types to use default_factory

    • +

  • ruff: added rule-set “B” (flake8-bugbear)

    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.6 and ospx>=0.2.8

    • +
+
+
+
+

0.3.0 - 2023-01-09

+

v0.3.0 is a major update comprising one breaking change (see below). +Users are encouraged to update to this version.

+
+

Breaking Change

+
    +

  • Moved classes ‘Case’ and ‘Parameter’ from farn.farn to farn.core
    +As a consequence, if you imported these classes in your code, you need to +adapt the respective import statements. I.e.
    +old

    +
    from farn.farn import Case, Parameter
+
    +
    +

    new

    +
    from farn.core import Case, Parameter
+
    +
    +
    • +
+
+
+

Added

+
    +

  • Added a ‘Cases’ class, acting as a container for Case instances. +Cases inherits from List[Case] and can hence transparently be used as a Python list type. +However, Cases provides additional convenience methods to export the attributes of all contained Case instances to a pandas DataFrame (Cases.to_pandas()) or to a numpy ndarray (Cases.to_numpy())

    +Cases is located in the farn.core sub-package and can be imported from there, i.e:

    +
    from farn.core import Case, Cases, Parameter
+
    +
    +
    • +
+
+
+
+

0.2.7 - 2023-01-04

+
+

Changed

+
    +

  • Linter: Migrated from flake8 to ruff.
    +(Added ruff; removed flake8 and isort)

    • +

  • Adjusted GitHub CI workflow accordingly.
    +(Added ruff job; removed flake8 and isort jobs)

    • +

  • VS Code settings: Adjusted Pylance configuration

    • +
+
+
+

Added

+
    +

  • Added a batch file ‘qa.bat’ in root folder to ease local execution of code quality checks

    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.5 and ospx>=0.2.7

    • +
+
+
+
+

0.2.6 - 2022-12-12

+
+

Dependencies

+
    +

  • updated to ospx>=0.2.6

    • +
+
+
+
+

0.2.5 - 2022-12-12

+
+

Changed

+
    +

  • Moved dev-only dependencies from requirements.txt to requirements-dev.txt

    • +

  • farn/__init__.py : ensured that imported symbols get also exported
    +(added “as” clause -> “from x import y as y” instead of only “from x import y”)

    • +

  • sampling.py: refactored for cleaner code

    • +

  • Configured code quality tools flake8, black, isort, pyright

    • +

  • Improved code quality, resolving all warnings and errors flagged by the configured code quality tools +(flake8, black, isort, pyright, sourcery)

    • +
+
+
+

Added

+
    +

  • Added GitHub workflow ‘main.yml’ for continuous integration (runs all CI tasks except Sphinx)

    +
      +

    • format checks: black, isort

      • +

    • lint check: flake8, flake8-bugbear

      • +

    • type check: pyright

      • +

    • test: uses tox to run pytest on {Windows, Linux, MacOS} with {py39, py310}

      • +

    • publish: publishing to PyPI (runs only on push of new tag vx.x.x, and after all other jobs succeeded)

      • +

    • merge_to_release_branch: merge tagged commit to release branch (runs after publish)

      • +
    +
    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.4

    • +
+
+
+
+

0.2.4 - 2022-12-01

+
+

Changed

+
    +

  • Code formatting: Changed from yapf to black

    • +

  • STYLEGUIDE.md : Adjusted to match black formatting

    • +

  • VS Code settings: Updated to use black as formatter

    • +

  • requirements.txt: Updated dependencies to their most recent versions

    • +

  • GitHub actions (yml files): Updated following actions to their most recent versions:

    +
      +

    • checkout@v1 -> checkout@v3

      • +

    • setup-python@v2 -> setup-python@v4

      • +

    • cache@v2 -> cache@v3

      • +
    +
    • +
+
+
+

Added

+
    +

  • Added sourcery configuration (.sourcery.yaml)

    • +

  • Added py.typed file into the package root folder and included it setup.cfg as package_data

    • +
+
+
+
+

0.2.3 - 2022-11-08

+
+

Changed

+
    +

  • sampling.py: sampling adapted, removed unused (and non-preferable) options

    • +

  • dependencies:

    +
      +

    • upgraded to dictIO >= 0.2.2 (now supporting references and expressions in JSON dicts)

      • +

    • upgraded to ospx >= 0.2.4

      • +

    • changed from pyDOE>=0.3.8 to pyDOE2>=1.3.0

      • +
    +
    • +
+
+
+
+

0.2.2 - 2022-10-05

+
+

Changed

+
    +

  • dependencies:

    +
      +

    • upgraded to ospx >= 0.2.3

      • +
    +
    • +
+
+
+
+

0.2.1 - 2022-10-01

+
+

Changed

+
    +

  • dependencies:

    +
      +

    • upgraded to dictIO >= 0.2.0

      • +

    • upgraded to ospx >= 0.2.1

      • +
    +
    • +
+
+
+
+

0.2.0 - 2022-09-28

+
+

Changed

+
    +

  • Dependencies:

    +
      +

    • upgraded to ospx >= 0.2.0

      • +

    • upgraded to dictIO >= 0.1.2

      • +
    +
    • +
+
+
+
+

0.1.2 - 2022-08-19

+
+

Changed

+
    +

  • farn.py:

    +
      +

    • create_samples(): Removed undocumented return value ‘layers’. This was simply wrong. create_samples() is not meant to return anything.

      • +
    +
    • +

  • subProcess.py:

    +
      +

    • Changed level of ‘per case’ log messages from INFO to DEBUG, to reduce cluttering of log.

      • +
    +
    • +
+
+
+

Added

+
    +

  • farn CLI (and farn.run_farn() API):

    +
      +

    • EXPERIMENTAL FEATURE: Added –batch option. Default is False. The batch option lets farn execute commands in batch mode, i.e. asynchroneous instead of sequential.

      • +
    +
    • +
+
+
+

Fixed

+
    +

  • sampling.py:

    +
      +

    • uniformLhs sampling: Corrected the BoundingBox code for the case where Lhs sampling is requested with only one single parameter varied (i.e. 1-dimensional Lhs)

      • +
    +
    • +

  • farn.py:

    +
      +

    • Additional log file handler for farn gets registered only once. Multiple calls to _configure_additional_logging_handler_exclusively_for_farn() will not create multiple handlers, if the file handler for the log file already exists.

      • +
    +
    • +
+
+
+
+

0.1.1 - 2022-05-30

+
+

Changed

+
    +

  • Sphinx documentation: Added Changelogs (for combined documentation)

    • +

  • updated dependency ospx to version >=0.1.1

    • +
+
+
+
+

0.1.0 - 2022-05-28

+
+

Changed

+
    +

  • Simplified imports from namespace farn. Example:

    +
      +

    • Old (<= v0.0.22):

      +
      from farn.farn import run_farn
+
      +
      +
      • +

    • New:

      +
      from farn import run_farn
+
      +
      +
      • +
    +
    • +

  • Use new simplified imports from namespace dictIO (using updated version of dictIO package)

    • +

  • farn.py

    +
      +

    • Renamed following functions:

      +
        +

      • run_sampling() -> create_samples()

        • +

      • generate_samples_for_layer() -> create_samples_in_layer()

        • +

      • register_cases() -> create_cases()

        • +

      • generate_case_folder_structure() -> create_case_folders()

        • +

      • generate_case_lists() -> create_case_list_files()

        • +

      • _create_param_dict_file_in_case_folders() -> create_param_dict_files()

        • +

      • _execute_command_set_in_case_folders() -> execute_command_set()

        • +
      +
      • +

    • Introduced Dataclass ‘Parameter’

      • +

    • Removed method add_uservars() in dataclass Case (moved the respective code into create_cases() )

      • +

    • run_farn(): Removed the ignore_errors argument

      • +

    • farnDict ‘_samples’ section -> changed naming of ‘_names’ element to ‘_case_name’, to improve clarity of its meaning

      • +

    • Smaller refactorings to improve code clarity and testability

      • +
    +
    • +

  • cli/farn.py

    +
      +

    • Removed the -i / –ignore-errors argument

      • +
    +
    • +
+
+
+
+

0.0.22 - 2022-05-09

+
    +

  • First public release

    • +
+
+
+

0.0.17 - 2022-02-14

+
+

Added

+
    +

  • Added support for Python 3.10

    • +
+ + +
+
+
+ +
+
+
+ +
+ + +
+
+
+
+ Copyright © 2024, DNV SE. All rights reserved. +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/CHANGELOG_dictIO.html b/CHANGELOG_dictIO.html new file mode 100644 index 00000000..670bb7f9 --- /dev/null +++ b/CHANGELOG_dictIO.html @@ -0,0 +1,1121 @@ + + + + + + + + + dictIO - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO

+

All notable changes to the dictIO project will be documented in this file.
+The changelog format is based on Keep a Changelog.

+
+

Unreleased

+

-/-

+
+
+

0.4.0 - 2024-11-11

+
+

Breaking changes

+
    +

  • Renamed modules: Following modules have been renamed in order to comply with PEP8 naming conventions:
    +dictIO.dictReader -> dictIO.dict_reader
    +dictIO.dictWriter -> dictIO.dict_writer
    +dictIO.dictParser -> dictIO.dict_parser
    +dictIO.cppDict -> dictIO.cpp_dict

    • +

  • Module formatter.py :
    +Renamed Formatter.format_type() -> Formatter.format_value()

    • +

  • Module parser.py :
    +Renamed Parser.parse_type() -> Parser.parse_value()
    +Renamed Parser.parse_types() -> Parser.parse_values()

    • +

  • class CppDict in module dictIO.cppDict has been replaced with the new class SDict[K, V] in module dictIO.dict.
    +In order to maintain backward compatibility, a thin wrapper class named CppDict is kept in version ~0.4.0. +It is marked as deprecated, though, and will be removed with release 0.5.0.

    • +

  • Where CppDict inherited from UserDict, SDict inherits directly from Python’s dict class, +allowing to use it in any context where a dict or any other MutableMapping is expected.

    • +

  • SDict is generic: Static type checkers will hence require type arguments when SDict is used.
    +Where in dictIO < 0.4.0 you could write
    +my_dict: CppDict = CppDict(),
    +you will now need to specify the type arguments, e.g.
    +my_dict: SDict[str, Any] = SDict().
    +With this change, type hinting is in line with how Python’s builtin dict class works, and offers more control in static type checking.

    • +
+
+
+

Changed

+
    +

  • Changed from pip/tox to uv as package manager

    • +

  • README.md : Completely rewrote section “Development Setup”, introducing uv as package manager.

    • +

  • Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI

    • +

  • Updated copyright statement

    • +

  • VS Code settings: Turned off automatic venv activation

    • +

  • Replaced black formatter with ruff formatter

    • +
+
+
+

Solved

+
    +

  • Sphinx documentation: Resolved issue that documentation of class members was generated twice.

    • +
+
+
+

Added

+
    +

  • Sphinx documentation: Added extension to support Markdown-based diagrams created with Mermaid.

    • +

  • Added instance methods dump() and load() to SDict

    • +

  • Added mypy as static type checker (in addition to pyright)

    • +
+
+
+

GitHub workflows

+
    +

  • (all workflows): Adapted to use uv as package manager

    • +

  • _test_future.yml : updated Python version to 3.13.0-alpha - 3.13.0

    • +

  • _test_future.yml : updated name of test job to ‘test313’

    • +
+
+
+

Dependencies

+
    +

  • Updated to ruff>=0.6.3 (from ruff==0.4.2)

    • +

  • Updated to pyright>=1.1.378 (from pyright==1.1.360)

    • +

  • Updated to sourcery>=1.22 (from sourcery==1.16)

    • +

  • Updated to pytest>=8.3 (from pytest>=8.2)

    • +

  • Updated to Sphinx>=8.0 (from Sphinx>=7.3)

    • +

  • Updated to sphinx-argparse-cli>=1.17 (from sphinx-argparse-cli>=1.16)

    • +

  • Updated to myst-parser>=4.0 (from myst-parser>=3.0)

    • +

  • Updated to furo>=2024.8 (from furo>=2024.5)

    • +

  • updated to setup-python@v5 (from setup-python@v4)

    • +

  • updated to actions-gh-pages@v4 (from actions-gh-pages@v3)

    • +

  • updated to upload-artifact@v4 (from upload-artifact@v3)

    • +

  • Updated to download-artifact@v4 (from download-artifact@v3)

    • +

  • updated to checkout@v4 (from checkout@v3)

    • +
+
+
+
+

0.3.4 - 2024-05-22

+
+

Dependencies

+
    +

  • updated to ruff==0.4.2 (from ruff==0.2.1)

    • +

  • updated to pyright==1.1.360 (from pyright==1.1.350)

    • +

  • updated to sourcery==1.16 (from sourcery==1.15)

    • +

  • updated to lxml>=5.2 (from lxml>=5.1)

    • +

  • updated to types-lxml>=2024.4 (from types-lxml>=5.1)

    • +

  • updated to pytest>=8.2 (from pytest>=7.4)

    • +

  • updated to pytest-cov>=5.0 (from pytest-cov>=4.1)

    • +

  • updated to Sphinx>=7.3 (from Sphinx>=7.2)

    • +

  • updated to sphinx-argparse-cli>=1.15 (from sphinx-argparse-cli>=1.11)

    • +

  • updated to myst-parser>=3.0 (from myst-parser>=2.0)

    • +

  • updated to furo>=2024.4 (from furo>=2023.9.10)

    • +

  • updated to numpy>=1.26,<2.0 (from numpy>=1.26)

    • +

  • removed black

    • +
+
+
+

Changed

+
    +

  • replaced black formatter with ruff formatter

    • +

  • Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI

    • +

  • Updated copyright statement

    • +

  • VS Code settings: Turned off automatic venv activation

    • +
+
+
+
+

0.3.3 - 2024-02-21

+
+

Hotfix

+
    +

  • corrected name of cli script (wrong: dictIO correct: dictParser)

    • +
+
+
+
+

0.3.2 - 2024-02-21

+
+

Added

+
    +

  • README.md : Under Development Setup, added a step to install current package in “editable” mode, using the pip install -e option. +This removes the need to manually add /src to the PythonPath environment variable in order for debugging and tests to work.

    • +
+
+
+

Removed

+
    +

  • VS Code settings: Removed the setting which added the /src folder to PythonPath. This is no longer necessary. Installing the project itself as a package in “editable” mode, using the pip install -e option, solves the issue and removes the need to manually add /src to the PythonPath environment variable.

    • +
+
+
+

Changed

+
    +

  • Moved all project configuration from setup.cfg to pyproject.toml

    • +

  • Moved all tox configuration from setup.cfg to tox.ini.

    • +

  • Moved pytest configuration from pyproject.toml to pytest.ini

    • +

  • Deleted setup.cfg

    • +
+
+
+

Dependencies

+
    +

  • updated to black[jupyter]==24.1 (from black[jupyter]==23.12)

    • +

  • updated to version: ‘==24.1’ (from version: ‘==23.12’)

    • +

  • updated to ruff==0.2.1 (from ruff==0.1.8)

    • +

  • updated to pyright==1.1.350 (from pyright==1.1.338)

    • +

  • updated to sourcery==1.15 (from sourcery==1.14)

    • +

  • updated to lxml>=5.1 (from lxml>=4.9)

    • +
+
+
+
+

0.3.1 - 2024-01-09

+
+

Solved

+
    +

  • Solved a bug that led to single character references not being identified +(solves #14).

    • +
+
+
+
+

0.3.0 - 2024-01-08

+
+

Changed

+
    +

  • Enabled recognition of strings with nested quotes in it (solves #2)

    • +

  • GitHub workflows: Included Python 3.12 release version as standard, and Python 3.13.0a2 as “future” test.

    • +
+
+
+

Dependencies

+
    +

  • updated to black[jupyter]==23.12 (from black[jupyter]==23.11)

    • +

  • updated to ruff==0.1.8 (from ruff==0.1.6)

    • +

  • updated to pyright==1.1.338 (from pyright==1.1.336)

    • +
+
+
+
+

0.2.9 - 2023-09-20

+
+

Dependencies

+
    +

  • Updated dependencies to latest versions

    • +
+
+
+
+

0.2.8 - 2023-06-22

+
+

Changed

+
    +

  • Modularized GitHub workflows

    • +

  • Changed default Python version in GitHub workflows from 3.10 to 3.11

    • +
+
+
+

Dependencies

+
    +

  • requirements-dev.txt: Updated dependencies to latest versions

    • +
+
+
+
+

0.2.7 - 2023-05-04

+
+

Changed

+
    +

  • dependencies: updated dependencies to latest versions

    • +

  • ruff: added rule-set “B” (flake8-bugbear)

    • +
+
+
+
+

0.2.6 - 2023-01-11

+
+

Changed

+
    +

  • Added missing DocStrings for public classes, methods and functions

    • +

  • Changed links to package documentation to open README.html, not the default index page

    • +
+
+
+
+

0.2.5 - 2023-01-04

+
+

Changed

+
    +

  • Linter: Migrated from flake8 to ruff.
    +(Added ruff; removed flake8 and isort)

    • +

  • Adjusted GitHub CI workflow accordingly.
    +(Added ruff job; removed flake8 and isort jobs)

    • +

  • VS Code settings: Adjusted Pylance configuration

    • +

  • Sphinx documentation: Rebuilt API documentation

    • +
+
+
+

Added

+
    +

  • Added a batch file ‘qa.bat’ in root folder to ease local execution of code quality checks

    • +
+
+
+
+

0.2.4 - 2022-12-12

+
+

Changed

+
    +

  • Moved dev-only dependencies from requirements.txt to requirements-dev.txt

    • +

  • dictIO/__utils__.py : ensured that imported symbols get also exported
    +(added “as” clause -> “from x import y as y” instead of only “from x import y”)

    • +

  • Configured code quality tools flake8, black, isort, pyright

    • +

  • Improved code quality, resolving all warnings and errors flagged by the configured code quality tools +(flake8, black, isort, pyright, sourcery)

    • +
+
+
+

Added

+
    +

  • Added support for selected numpy functions (diag, eye, ones, zeros) +which can now be used in expressions.
    +This is an experimental feature which might be removed or changed in future.

    • +

  • Added GitHub workflow ‘main.yml’ for continuous integration (runs all CI tasks except Sphinx)

    +
      +

    • format checks: black, isort

      • +

    • lint check: flake8, flake8-bugbear

      • +

    • type check: pyright

      • +

    • test: uses tox to run pytest on {Windows, Linux, MacOS} with {py39, py310}

      • +

    • publish: publishing to PyPI (runs only on push of new tag vx.x.x, and after all other jobs succeeded)

      • +

    • merge_to_release_branch: merge tagged commit to release branch (runs after publish)

      • +
    +
    • +
+
+
+
+

0.2.3 - 2022-12-01

+
+

Changed

+
    +

  • Code formatting: Changed from yapf to black

    • +

  • STYLEGUIDE.md : Adjusted to match black formatting

    • +

  • VS Code settings: Updated to use black as formatter

    • +

  • requirements.txt: Updated dependencies to their most recent versions

    • +

  • GitHub actions (yml files): Updated following actions to their most recent versions:

    +
      +

    • checkout@v1 -> checkout@v3

      • +

    • setup-python@v2 -> setup-python@v4

      • +

    • cache@v2 -> cache@v3

      • +
    +
    • +
+
+
+

Added

+
    +

  • Added sourcery configuration (.sourcery.yaml)

    • +

  • Added py.typed file into the package root folder and included it setup.cfg as package_data

    • +

  • Documentation: Included sub-package dictIO.utils in documentation

    • +
+
+
+
+

0.2.2 - 2022-11-08

+
+

Added

+
    +

  • JsonParser: JsonParser now supports the usage of references and expressions, similar to the CppParser.

    • +
+
+
+
+

0.2.1 - 2022-10-13

+
+

Solved

+
    +

  • XmlParser: Solved a bug where default namespaces in an XML file would not be parsed correctly.

    • +
+
+
+
+

0.2.0 - 2022-09-29

+
+

Added

+
    +

  • dictIO.utils.path.py: Added two new functions

    +
      +

    • highest_common_root_folder(paths)

      • +

    • relative_path(from_path, to_path)

      • +
    +
    • +
+
+
+

Changed

+
    +

  • Replaced usages of pathlib.Path.resolve_to() with dictIO.utils.path.relative_path()

    • +
+
+
+

Removed

+
    +

  • dictIO.utils.path.py: Removed obsolete function silent_remove()

    • +
+
+
+
+

0.1.2 - 2022-09-27

+
+

Solved

+
    +

  • XmlParser: Changed how empty XML nodes get parsed.
    +The value for an empty node is now saved as an empty dict, i.e. {}, instead of None. +This change solves issue #4.
    +Problem was that None is not iterable, and code such as the following had caused an exception:

    +
    if '_attributes' in my_parsed_xml_dict[node_key]:
+    ...
+
    +
    +

    because my_parsed_xml_dict[node_key] had been None.

    +

    Now, with the code change in place, my_parsed_xml_dict[node_key] would resolve to an empty dict ( {} ) instead of to None. As a dict is formally iterable (even when empty), querying code as above does no longer crash.

    +
    • +
+
+
+
+

0.1.1 - 2022-08-19

+
+

Added

+
    +

  • cppDict:

    +
      +

    • Added method include(dict_to_include). +This method adds an include directive for the passed in dict inside the dict the method is called on.

      • +
    +
    • +
+
+
+
+

0.1.0 - 2022-05-28

+
+

Changed

+
    +

  • Simplified imports from namespace dictIO. Example:

    +
      +

    • Old (<= v0.0.22):

      +
      from dictIO.dictParser import DictParser
+
      +
      +
      • +

    • New:

      +
      from dictIO import DictParser
+
      +
      +
      • +
    +
    • +

  • parser.py

    +
      +

    • Parser.remove_quotes_from_string()

      +
        +

      • Changed default of ‘all’ argument from True to False
        +This change was introduced in order to, by default, protect inner quotes in i.e. a farn filter expression “var in [‘item1’, ‘item2’]” from being removed.

        • +
      +
      • +

    • CppParser._parse_tokenized_dict()

      +
        +

      • Changed implementation of the conditional code where a key value pair gets parsed.
        +This change was introduced in order to better identify invalid key value pairs.
        +Two invalid keys were added in test_parser_dict (section ‘invalid’) and a respective test was added.

        • +
      +
      • +
    +
    • +

  • formatter.py

    +
      +

    • JsonFormatter.insert_includes()

      +
        +

      • Changed correction of backslashes, so that backslashes in include paths are not substituted by forwardslashes but actually escaped in Json compliant way.

        • +
      +
      • +
    +
    • +

  • dictWriter.py

    +
      +

    • DictWriter.write()

      +
        +

      • Changed default of ‘mode’ argument from ‘w’ (overwrite) to ‘a’ (append)

        • +
      +
      • +
    +
    • +

  • utils\strings.py

    +
      +

    • plural() function moved to farn package (-> moved into utils\logging.py module in farn)
      +It was moved since the plural() function is currently used in farn logging only (neither in dictIO nor in ospx).

      • +
    +
    • +
+
+
+
+

0.0.22 - 2022-05-09

+
    +

  • First public release

    • +
+
+
+

0.0.17 - 2022-02-14

+
+

Added

+
    +

  • Added support for Python 3.10

    • +
+ +
+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/CHANGELOG_farn.html b/CHANGELOG_farn.html new file mode 100644 index 00000000..314728f1 --- /dev/null +++ b/CHANGELOG_farn.html @@ -0,0 +1,1196 @@ + + + + + + + + + farn - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn

+

All notable changes to the farn project will be documented in this file.
+The changelog format is based on Keep a Changelog.

+
+

Unreleased

+

-/-

+
+
+

[0.4.0] - 2024-11-11

+
+

Breaking changes

+
    +

  • The code has been adapted to dictIO 0.4.0
    +dictIO 0.4.0 introduced some breaking changes. With the current release 0.4.0 of farn, the code base has been adapted to these in changes.
    +The most prominent change being that class dictIO.CppDict has been replaced by class dictIO.SDict.

    • +
+
+
+

Changed

+
    +

  • Changed from pip/tox to uv as package manager

    • +

  • README.md : Completely rewrote section “Development Setup”, introducing uv as package manager.

    • +

  • Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI

    • +

  • Updated copyright statement

    • +

  • VS Code settings: Turned off automatic venv activation

    • +

  • Replaced black formatter with ruff formatter

    • +
+
+
+

Solved

+
    +

  • Sphinx documentation: Resolved issue that documentation of class members was generated twice.

    • +
+
+
+

Added

+
    +

  • Sphinx documentation: Added extension to support Markdown-based diagrams created with Mermaid.

    • +

  • Added mypy as static type checker (in addition to pyright)

    • +
+
+
+

GitHub workflows

+
    +

  • (all workflows): Adapted to use uv as package manager

    • +

  • _test_future.yml : updated Python version to 3.13.0-alpha - 3.13.0

    • +

  • _test_future.yml : updated name of test job to ‘test313’

    • +
+
+
+

Dependencies

+
    +

  • Updated to dictIO>=0.4.0 (from dictIO>=0.3.4)

    • +

  • Updated to ospx>=0.3.0 (from ospx>=0.2.14)

    • +

  • Updated to ruff>=0.6.3 (from ruff==0.4.2)

    • +

  • Updated to pyright>=1.1.378 (from pyright==1.1.360)

    • +

  • Updated to sourcery>=1.22 (from sourcery==1.16)

    • +

  • Updated to pytest>=8.3 (from pytest>=8.2)

    • +

  • Updated to Sphinx>=8.0 (from Sphinx>=7.3)

    • +

  • Updated to sphinx-argparse-cli>=1.17 (from sphinx-argparse-cli>=1.16)

    • +

  • Updated to myst-parser>=4.0 (from myst-parser>=3.0)

    • +

  • Updated to furo>=2024.8 (from furo>=2024.5)

    • +

  • updated to setup-python@v5 (from setup-python@v4)

    • +

  • updated to actions-gh-pages@v4 (from actions-gh-pages@v3)

    • +

  • updated to upload-artifact@v4 (from upload-artifact@v3)

    • +

  • Updated to download-artifact@v4 (from download-artifact@v3)

    • +

  • updated to checkout@v4 (from checkout@v3)

    • +
+
+
+
+

0.3.7 - 2024-05-22

+
+

Dependencies

+
    +

  • updated to ruff==0.4.2 (from ruff==0.2.1)

    • +

  • updated to pyright==1.1.360 (from pyright==1.1.350)

    • +

  • updated to sourcery==1.16 (from sourcery==1.15)

    • +

  • updated to lxml>=5.2 (from lxml>=5.1)

    • +

  • updated to types-lxml>=2024.4 (from types-lxml>=5.1)

    • +

  • updated to scipy>=1.13 (from scipy>=1.12)

    • +

  • updated to Pillow>=10.3 (from Pillow>=10.2)

    • +

  • updated to pytest>=8.2 (from pytest>=7.4)

    • +

  • updated to pytest-cov>=5.0 (from pytest-cov>=4.1)

    • +

  • updated to Sphinx>=7.3 (from Sphinx>=7.2)

    • +

  • updated to sphinx-argparse-cli>=1.15 (from sphinx-argparse-cli>=1.11)

    • +

  • updated to myst-parser>=3.0 (from myst-parser>=2.0)

    • +

  • updated to furo>=2024.4 (from furo>=2023.9.10)

    • +

  • updated to dictIO>=0.3.4 (from dictIO>=0.3.3)

    • +

  • updated to ospx>=0.2.14 (from ospx>=0.2.13)

    • +

  • updated to numpy>=1.26,<2.0 (from numpy>=1.26)

    • +

  • updated to matplotlib>=3.9 (from matplotlib>=3.8)

    • +

  • removed black

    • +
+
+
+

Changed

+
    +

  • replaced black formatter with ruff formatter

    • +

  • Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI

    • +

  • Updated copyright statement

    • +

  • VS Code settings: Turned off automatic venv activation

    • +
+
+
+

Added

+
    +

  • farn.core.case.Case: Added method add_parameters(), which allows to manually add user-defined parameters to a Case.

    • +
+
+
+
+

0.3.6 - 2024-02-21

+
+

Added

+
    +

  • README.md : Under Development Setup, added a step to install current package in “editable” mode, using the pip install -e option. +This removes the need to manually add /src to the PythonPath environment variable in order for debugging and tests to work.

    • +
+
+
+

Removed

+
    +

  • VS Code settings: Removed the setting which added the /src folder to PythonPath. This is no longer necessary. Installing the project itself as a package in “editable” mode, using the pip install -e option, solves the issue and removes the need to manually add /src to the PythonPath environment variable.

    • +
+
+
+

Changed

+
    +

  • Moved all project configuration from setup.cfg to pyproject.toml

    • +

  • Moved all tox configuration from setup.cfg to tox.ini.

    • +

  • Moved pytest configuration from pyproject.toml to pytest.ini

    • +

  • Deleted setup.cfg

    • +
+
+
+

Dependencies

+
    +

  • updated to black[jupyter]==24.1 (from black[jupyter]==23.12)

    • +

  • updated to version: ‘==24.1’ (from version: ‘==23.12’)

    • +

  • updated to ruff==0.2.1 (from ruff==0.1.8)

    • +

  • updated to pyright==1.1.350 (from pyright==1.1.338)

    • +

  • updated to sourcery==1.15 (from sourcery==1.14)

    • +

  • updated to lxml>=5.1 (from lxml>=4.9)

    • +

  • updated to scipy>=1.12 (from scipy>=1.11)

    • +

  • updated to pandas>=2.2 (from pandas>=2.1)

    • +

  • updated to Pillow>=10.2 (from Pillow>=10.1)

    • +

  • -/-

    • +
+
+
+
+

0.3.5 - 2024-01-09

+
+

Changed

+
    +

  • farn/sampling/sampling.py:

    +
      +

    • _generate_values_using_uniform_lhs_sampling(): +replaced SALib latin with pyDOE2 lhs

      • +

    • _generate_values_using_sobol_sampling(): +replaced sobol-seq with scipy.stats.qmc.sobol

      • +

    • removed orphaned _cov argument from normalLhs sampling

      • +
    +
    • +
+
+
+

Dependencies

+
    +

  • Upgraded from pyDOE2>=1.3 to pyDOE3>=1.0

    • +

  • Removed SALib and sobol-seq

    • +

  • Updated to dictIO>=0.3.1 and ospx>=0.2.12

    • +

  • Updated other dependencies to latest versions

    • +
+
+
+
+

0.3.4 - 2023-09-25

+
+

Dependencies

+
    +

  • Updated dependencies to latest versions

    • +
+
+
+
+

0.3.3 - 2023-06-22

+
+

Changed

+
    +

  • Modularized GitHub workflows

    • +

  • Changed default Python version in GitHub workflows from 3.10 to 3.11

    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.8 and ospx>=0.2.10

    • +

  • requirements-dev.txt: Updated dependencies to latest versions

    • +
+
+
+
+

0.3.2 - 2023-05-04

+
+

Changed

+
    +

  • dependencies: updated dependencies to latest versions

    • +
+
+
+
+

0.3.1 - 2023-01-11

+
+

Changed

+
    +

  • Added missing DocStrings for public classes, methods and functions

    • +

  • Changed links to package documentation to open README.html, not the default index page

    • +

  • data classes: changed initialisation of mutable types to use default_factory

    • +

  • ruff: added rule-set “B” (flake8-bugbear)

    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.6 and ospx>=0.2.8

    • +
+
+
+
+

0.3.0 - 2023-01-09

+

v0.3.0 is a major update comprising one breaking change (see below). +Users are encouraged to update to this version.

+
+

Breaking Change

+
    +

  • Moved classes ‘Case’ and ‘Parameter’ from farn.farn to farn.core
    +As a consequence, if you imported these classes in your code, you need to +adapt the respective import statements. I.e.
    +old

    +
    from farn.farn import Case, Parameter
+
    +
    +

    new

    +
    from farn.core import Case, Parameter
+
    +
    +
    • +
+
+
+

Added

+
    +

  • Added a ‘Cases’ class, acting as a container for Case instances. +Cases inherits from List[Case] and can hence transparently be used as a Python list type. +However, Cases provides additional convenience methods to export the attributes of all contained Case instances to a pandas DataFrame (Cases.to_pandas()) or to a numpy ndarray (Cases.to_numpy())

    +Cases is located in the farn.core sub-package and can be imported from there, i.e:

    +
    from farn.core import Case, Cases, Parameter
+
    +
    +
    • +
+
+
+
+

0.2.7 - 2023-01-04

+
+

Changed

+
    +

  • Linter: Migrated from flake8 to ruff.
    +(Added ruff; removed flake8 and isort)

    • +

  • Adjusted GitHub CI workflow accordingly.
    +(Added ruff job; removed flake8 and isort jobs)

    • +

  • VS Code settings: Adjusted Pylance configuration

    • +
+
+
+

Added

+
    +

  • Added a batch file ‘qa.bat’ in root folder to ease local execution of code quality checks

    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.5 and ospx>=0.2.7

    • +
+
+
+
+

0.2.6 - 2022-12-12

+
+

Dependencies

+
    +

  • updated to ospx>=0.2.6

    • +
+
+
+
+

0.2.5 - 2022-12-12

+
+

Changed

+
    +

  • Moved dev-only dependencies from requirements.txt to requirements-dev.txt

    • +

  • farn/__init__.py : ensured that imported symbols get also exported
    +(added “as” clause -> “from x import y as y” instead of only “from x import y”)

    • +

  • sampling.py: refactored for cleaner code

    • +

  • Configured code quality tools flake8, black, isort, pyright

    • +

  • Improved code quality, resolving all warnings and errors flagged by the configured code quality tools +(flake8, black, isort, pyright, sourcery)

    • +
+
+
+

Added

+
    +

  • Added GitHub workflow ‘main.yml’ for continuous integration (runs all CI tasks except Sphinx)

    +
      +

    • format checks: black, isort

      • +

    • lint check: flake8, flake8-bugbear

      • +

    • type check: pyright

      • +

    • test: uses tox to run pytest on {Windows, Linux, MacOS} with {py39, py310}

      • +

    • publish: publishing to PyPI (runs only on push of new tag vx.x.x, and after all other jobs succeeded)

      • +

    • merge_to_release_branch: merge tagged commit to release branch (runs after publish)

      • +
    +
    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.4

    • +
+
+
+
+

0.2.4 - 2022-12-01

+
+

Changed

+
    +

  • Code formatting: Changed from yapf to black

    • +

  • STYLEGUIDE.md : Adjusted to match black formatting

    • +

  • VS Code settings: Updated to use black as formatter

    • +

  • requirements.txt: Updated dependencies to their most recent versions

    • +

  • GitHub actions (yml files): Updated following actions to their most recent versions:

    +
      +

    • checkout@v1 -> checkout@v3

      • +

    • setup-python@v2 -> setup-python@v4

      • +

    • cache@v2 -> cache@v3

      • +
    +
    • +
+
+
+

Added

+
    +

  • Added sourcery configuration (.sourcery.yaml)

    • +

  • Added py.typed file into the package root folder and included it setup.cfg as package_data

    • +
+
+
+
+

0.2.3 - 2022-11-08

+
+

Changed

+
    +

  • sampling.py: sampling adapted, removed unused (and non-preferable) options

    • +

  • dependencies:

    +
      +

    • upgraded to dictIO >= 0.2.2 (now supporting references and expressions in JSON dicts)

      • +

    • upgraded to ospx >= 0.2.4

      • +

    • changed from pyDOE>=0.3.8 to pyDOE2>=1.3.0

      • +
    +
    • +
+
+
+
+

0.2.2 - 2022-10-05

+
+

Changed

+
    +

  • dependencies:

    +
      +

    • upgraded to ospx >= 0.2.3

      • +
    +
    • +
+
+
+
+

0.2.1 - 2022-10-01

+
+

Changed

+
    +

  • dependencies:

    +
      +

    • upgraded to dictIO >= 0.2.0

      • +

    • upgraded to ospx >= 0.2.1

      • +
    +
    • +
+
+
+
+

0.2.0 - 2022-09-28

+
+

Changed

+
    +

  • Dependencies:

    +
      +

    • upgraded to ospx >= 0.2.0

      • +

    • upgraded to dictIO >= 0.1.2

      • +
    +
    • +
+
+
+
+

0.1.2 - 2022-08-19

+
+

Changed

+
    +

  • farn.py:

    +
      +

    • create_samples(): Removed undocumented return value ‘layers’. This was simply wrong. create_samples() is not meant to return anything.

      • +
    +
    • +

  • subProcess.py:

    +
      +

    • Changed level of ‘per case’ log messages from INFO to DEBUG, to reduce cluttering of log.

      • +
    +
    • +
+
+
+

Added

+
    +

  • farn CLI (and farn.run_farn() API):

    +
      +

    • EXPERIMENTAL FEATURE: Added –batch option. Default is False. The batch option lets farn execute commands in batch mode, i.e. asynchroneous instead of sequential.

      • +
    +
    • +
+
+
+

Fixed

+
    +

  • sampling.py:

    +
      +

    • uniformLhs sampling: Corrected the BoundingBox code for the case where Lhs sampling is requested with only one single parameter varied (i.e. 1-dimensional Lhs)

      • +
    +
    • +

  • farn.py:

    +
      +

    • Additional log file handler for farn gets registered only once. Multiple calls to _configure_additional_logging_handler_exclusively_for_farn() will not create multiple handlers, if the file handler for the log file already exists.

      • +
    +
    • +
+
+
+
+

0.1.1 - 2022-05-30

+
+

Changed

+
    +

  • Sphinx documentation: Added Changelogs (for combined documentation)

    • +

  • updated dependency ospx to version >=0.1.1

    • +
+
+
+
+

0.1.0 - 2022-05-28

+
+

Changed

+
    +

  • Simplified imports from namespace farn. Example:

    +
      +

    • Old (<= v0.0.22):

      +
      from farn.farn import run_farn
+
      +
      +
      • +

    • New:

      +
      from farn import run_farn
+
      +
      +
      • +
    +
    • +

  • Use new simplified imports from namespace dictIO (using updated version of dictIO package)

    • +

  • farn.py

    +
      +

    • Renamed following functions:

      +
        +

      • run_sampling() -> create_samples()

        • +

      • generate_samples_for_layer() -> create_samples_in_layer()

        • +

      • register_cases() -> create_cases()

        • +

      • generate_case_folder_structure() -> create_case_folders()

        • +

      • generate_case_lists() -> create_case_list_files()

        • +

      • _create_param_dict_file_in_case_folders() -> create_param_dict_files()

        • +

      • _execute_command_set_in_case_folders() -> execute_command_set()

        • +
      +
      • +

    • Introduced Dataclass ‘Parameter’

      • +

    • Removed method add_uservars() in dataclass Case (moved the respective code into create_cases() )

      • +

    • run_farn(): Removed the ignore_errors argument

      • +

    • farnDict ‘_samples’ section -> changed naming of ‘_names’ element to ‘_case_name’, to improve clarity of its meaning

      • +

    • Smaller refactorings to improve code clarity and testability

      • +
    +
    • +

  • cli/farn.py

    +
      +

    • Removed the -i / –ignore-errors argument

      • +
    +
    • +
+
+
+
+

0.0.22 - 2022-05-09

+
    +

  • First public release

    • +
+
+
+

0.0.17 - 2022-02-14

+
+

Added

+
    +

  • Added support for Python 3.10

    • +
+ + +
+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/CHANGELOG_ospx.html b/CHANGELOG_ospx.html new file mode 100644 index 00000000..a5b07674 --- /dev/null +++ b/CHANGELOG_ospx.html @@ -0,0 +1,1239 @@ + + + + + + + + + ospx - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx

+

All notable changes to the ospx project will be documented in this file.
+The changelog format is based on Keep a Changelog.

+
+

Unreleased

+

-/-

+
+
+

[0.3.0] - 2024-11-11

+
+

Breaking changes

+
    +

  • The code has been adapted to dictIO 0.4.0
    +dictIO 0.4.0 introduced some breaking changes. With the current release 0.3.0 of ospx, the code base has been adapted to these in changes.
    +The most prominent change being that class dictIO.CppDict has been replaced by class dictIO.SDict.

    • +
+
+
+

Changed

+
    +

  • Changed from pip/tox to uv as package manager

    • +

  • README.md : Completely rewrote section “Development Setup”, introducing uv as package manager.

    • +

  • Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI

    • +

  • Updated copyright statement

    • +

  • VS Code settings: Turned off automatic venv activation

    • +

  • Replaced black formatter with ruff formatter

    • +
+
+
+

Solved

+
    +

  • Sphinx documentation: Resolved issue that documentation of class members was generated twice.

    • +
+
+
+

Added

+
    +

  • Sphinx documentation: Added extension to support Markdown-based diagrams created with Mermaid.

    • +

  • Added mypy as static type checker (in addition to pyright)

    • +
+
+
+

GitHub workflows

+
    +

  • (all workflows): Adapted to use uv as package manager

    • +

  • _test_future.yml : updated Python version to 3.13.0-alpha - 3.13.0

    • +

  • _test_future.yml : updated name of test job to ‘test313’

    • +
+
+
+

Dependencies

+
    +

  • Updated to dictIO>=0.4.0 (from dictIO>=0.3.4)

    • +

  • Updated to ruff>=0.6.3 (from ruff==0.4.2)

    • +

  • Updated to pyright>=1.1.378 (from pyright==1.1.360)

    • +

  • Updated to sourcery>=1.22 (from sourcery==1.16)

    • +

  • Updated to pytest>=8.3 (from pytest>=8.2)

    • +

  • Updated to Sphinx>=8.0 (from Sphinx>=7.3)

    • +

  • Updated to sphinx-argparse-cli>=1.17 (from sphinx-argparse-cli>=1.16)

    • +

  • Updated to myst-parser>=4.0 (from myst-parser>=3.0)

    • +

  • Updated to furo>=2024.8 (from furo>=2024.5)

    • +

  • updated to setup-python@v5 (from setup-python@v4)

    • +

  • updated to actions-gh-pages@v4 (from actions-gh-pages@v3)

    • +

  • updated to upload-artifact@v4 (from upload-artifact@v3)

    • +

  • Updated to download-artifact@v4 (from download-artifact@v3)

    • +

  • updated to checkout@v4 (from checkout@v3)

    • +
+
+
+
+

0.2.14 - 2024-05-22

+
+

Dependencies

+
    +

  • updated to ruff==0.4.2 (from ruff==0.2.1)

    • +

  • updated to pyright==1.1.360 (from pyright==1.1.350)

    • +

  • updated to sourcery==1.16 (from sourcery==1.15)

    • +

  • updated to lxml>=5.2 (from lxml>=5.1)

    • +

  • updated to types-lxml>=2024.4 (from types-lxml>=5.1)

    • +

  • updated to pytest>=8.2 (from pytest>=7.4)

    • +

  • updated to pytest-cov>=5.0 (from pytest-cov>=4.1)

    • +

  • updated to Sphinx>=7.3 (from Sphinx>=7.2)

    • +

  • updated to sphinx-argparse-cli>=1.15 (from sphinx-argparse-cli>=1.11)

    • +

  • updated to myst-parser>=3.0 (from myst-parser>=2.0)

    • +

  • updated to furo>=2024.4 (from furo>=2023.9.10)

    • +

  • updated to numpy>=1.26,<2.0 (from numpy>=1.26)

    • +

  • updated to matplotlib>=3.9 (from matplotlib>=3.8)

    • +

  • updated to dictIO>=0.3.4 (from dictIO>=0.3.1)

    • +

  • removed black

    • +
+
+
+

Changed

+
    +

  • replaced black formatter with ruff formatter

    • +

  • Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI

    • +

  • Updated copyright statement

    • +

  • VS Code settings: Turned off automatic venv activation

    • +
+
+
+
+

0.2.13 - 2024-02-21

+
+

Added

+
    +

  • README.md : Under Development Setup, added a step to install current package in “editable” mode, using the pip install -e option. +This removes the need to manually add /src to the PythonPath environment variable in order for debugging and tests to work.

    • +
+
+
+

Removed

+
    +

  • VS Code settings: Removed the setting which added the /src folder to PythonPath. This is no longer necessary. Installing the project itself as a package in “editable” mode, using the pip install -e option, solves the issue and removes the need to manually add /src to the PythonPath environment variable.

    • +
+
+
+

Changed

+
    +

  • Moved all project configuration from setup.cfg to pyproject.toml

    • +

  • Moved all tox configuration from setup.cfg to tox.ini.

    • +

  • Moved pytest configuration from pyproject.toml to pytest.ini

    • +

  • Deleted setup.cfg

    • +
+
+
+

Dependencies

+
    +

  • updated to black[jupyter]==24.1 (from black[jupyter]==23.12)

    • +

  • updated to version: ‘==24.1’ (from version: ‘==23.12’)

    • +

  • updated to ruff==0.2.1 (from ruff==0.1.8)

    • +

  • updated to pyright==1.1.350 (from pyright==1.1.338)

    • +

  • updated to sourcery==1.15 (from sourcery==1.14)

    • +

  • updated to lxml>=5.1 (from lxml>=4.9)

    • +

  • updated to pandas>=2.2 (from pandas>=2.1)

    • +
+
+
+
+

0.2.12 - 2024-01-09

+

Maintenance Release

+
+

Dependencies

+
    +

  • Updated to dictIO>=0.3.1 (from dictIO>=0.2.9)

    • +

  • Updated other dependencies to latest versions

    • +
+
+
+
+

0.2.11 - 2023-09-25

+
+

Dependencies

+
    +

  • Updated dependencies to latest versions

    • +
+
+
+
+

0.2.10 - 2023-06-22

+
+

Changed

+
    +

  • Modularized GitHub workflows

    • +

  • Changed default Python version in GitHub workflows from 3.10 to 3.11

    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.8

    • +

  • requirements-dev.txt: Updated dependencies to latest versions

    • +
+
+
+
+

0.2.9 - 2023-05-04

+
+

Changed

+
    +

  • dependencies: updated dependencies to latest versions

    • +
+
+
+
+

0.2.8 - 2023-01-11

+
+

Changed

+
    +

  • Added missing DocStrings for public classes, methods and functions

    • +

  • Changed links to package documentation to open README.html, not the default index page

    • +

  • data classes: changed initialisation of mutable types to use default_factory

    • +

  • ruff: added rule-set “B” (flake8-bugbear)

    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.6

    • +
+
+
+
+

0.2.7 - 2023-01-04

+
+

Changed

+
    +

  • Linter: Migrated from flake8 to ruff.
    +(Added ruff; removed flake8 and isort)

    • +

  • Adjusted GitHub CI workflow accordingly.
    +(Added ruff job; removed flake8 and isort jobs)

    • +

  • VS Code settings: Adjusted Pylance configuration

    • +
+
+
+

Added

+
    +

  • Added a batch file ‘qa.bat’ in root folder to ease local execution of code quality checks

    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.5

    • +
+
+
+
+

0.2.6 - 2022-12-12

+
+

Changed

+
    +

  • Moved dev-only dependencies from requirements.txt to requirements-dev.txt

    • +

  • ospx/__init__.py and ospx/fmi/__init__.py : ensured that imported symbols get also exported
    +(added “as” clause -> “from x import y as y” instead of only “from x import y”)

    • +

  • Configured code quality tools flake8, black, isort, pyright

    • +

  • Improved code quality, resolving all warnings and errors flagged by the configured code quality tools +(flake8, black, isort, pyright, sourcery)

    • +
+
+
+

Added

+
    +

  • Added GitHub workflow ‘main.yml’ for continuous integration (runs all CI tasks except Sphinx)

    +
      +

    • format checks: black, isort

      • +

    • lint check: flake8, flake8-bugbear

      • +

    • type check: pyright

      • +

    • test: uses tox to run pytest on {Windows, Linux, MacOS} with {py39, py310}

      • +

    • publish: publishing to PyPI (runs only on push of new tag vx.x.x, and after all other jobs succeeded)

      • +

    • merge_to_release_branch: merge tagged commit to release branch (runs after publish)

      • +
    +
    • +
+
+
+

Dependencies

+
    +

  • updated to dictIO>=0.2.4

    • +
+
+
+
+

0.2.5 - 2022-12-01

+
+

Changed

+
    +

  • variable.py: get_fmi_data_type():

    +
      +

    • Removed the elif branch ‘isinstance(arg, Sequence)’.
      +It caused problems as it falsely returned the FMI type ‘Enumeration’ also for strings.
      +The respective elif branch is for the time being commented out.
      +However, a proper solution is needed as soon as xs:enumeration is used in an OSP case.
      +The problem is registered as Issue #5

      • +
    +
    • +

  • Code formatting: Changed from yapf to black

    • +

  • STYLEGUIDE.md : Adjusted to match black formatting

    • +

  • VS Code settings: Updated to use black as formatter

    • +

  • requirements.txt: Updated dependencies to their most recent versions

    • +

  • GitHub actions (yml files): Updated following actions to their most recent versions:

    +
      +

    • checkout@v1 -> checkout@v3

      • +

    • setup-python@v2 -> setup-python@v4

      • +

    • cache@v2 -> cache@v3

      • +
    +
    • +
+
+
+

Added

+
    +

  • watchCosim: Added commandline option –scale
    +(allows to scale the generated images by a factor)

    • +

  • Added sourcery configuration (.sourcery.yaml)

    • +

  • Added py.typed file into the package root folder and included it setup.cfg as package_data

    • +
+
+
+
+

0.2.4 - 2022-11-08

+
+

Changed

+
    +

  • Renamed module systemStructure.py to system.py
    +Accordingly, renamed also class SystemStructure to System.

    • +

  • Renamed some attributes in FMU class

    • +

  • dependencies:

    +
      +

    • upgraded to dictIO >= 0.2.2 (now supporting references and expressions in JSON dicts)

      • +
    +
    • +
+
+
+

Added

+
    +

  • \tests: Added spring_mass_damper example

    • +

  • \tests: Added test_fmu.py

    • +
+
+
+

Solved

+
    +

  • watchCosim.py : Added try-except statements to catch TypeErrors and ValueErrors when trying to plot non-numerical variables (i.e. String or None)

    • +
+
+
+
+

0.2.3 - 2022-10-05

+
+

Solved

+
    +

  • Importer:

    +
      +

    • Corrected a bug in OspSystemStructureImporter, where multiple connections between two components would not be imported (but only the last one survived). Now, also more than one connection in between two components are imported correctly.

      • +

    • OspSystemStructureImporter now resolves the type of initial values. I.e. If an initial value in OspSystemStructure is denoted as literal ‘1’ but with Type ‘Real’, then this initial value will be imported not as integer 1 but as float 1.0

      • +
    +
    • +
+
+
+
+

0.2.2 - 2022-10-05

+
+

Solved

+
    +

  • Connection:
    +Corrected a bug in Connection.is_variable_connection() and Connection.is_variable_group_connection() which led to Variable Connections not being resolved.

    • +
+
+
+
+

0.2.1 - 2022-10-01

+
+

Changed

+
    +

  • OspSimulationCase:
    +Changed setup(): FMU files get no longer copied into the case folder by default but stay where they are (i.e. in the library).
    +Only if an FMU is not reachable by a relative path from the case folder, the FMU will get copied into the case folder.

    • +

  • dependencies:

    +
      +

    • upgraded to dictIO >= 0.2.0

      • +
    +
    • +
+
+
+
+

0.2.0 - 2022-09-28

+
+

Solved

+
    +

  • importer.py:
    +Relative paths to libSource and FMUs are now properly resolved, relative to the target directory the OSPSystemStructure.xml is imported into (= folder in which the caseDict is created). +For libSource, by default the absolute path will be entered. This makes the caseDict insensitive when moved or copied into other (case) folders.

    • +
+
+
+

Changed

+
    +

  • OSPModelDescription.xml:
    +The handling of OSPModelDescription.xml files has changed:

    +
      +

    • no OSPModelDescription.xml files get written by default

      • +

    • existing OSPModelDescription.xml files will be kept

      • +
    +
    • +

  • dependencies:

    +
      +

    • upgraded to dictIO >= 0.1.2

      • +
    +
    • +
+
+
+

Added

+
    +

  • OSPSystemStructure.xml:

    +
      +

    • Added support for VariableGroups and VariableGroupConnections (as defined in OSP-IS).
      +importSystemStructure is now also able to import OSPSystemStructure.xml files that use Connections of OSP-IS type ‘VariableGroupConnection’.

      • +

    • Added support for stepSize attribute:
      +If a <Simulator> element in OSPSystemStructure.xml explicitely defines the stepSize attribute, and if the value given for a <Simulator>’s stepSize inside OSPSystemStructure.xml differs from the default stepSize defined in the FMU’s ModelDescription.xml, then the stepSize defined in OSPSystemStructure.xml prevails and will also explicitely be included in the OSPSystemStructure.xml file written by ospCaseBuilder.

      • +
    +
    • +
+
+
+
+

0.1.2 - 2022-08-19

+
+

Changed

+
    +

  • variable.py:

    +
      +

    • variable.start -> added type casting to setter property ensuring an already defined data_type of the variable is not altered when a new start value is set.

      • +
    +
    • +

  • watchCosim.py

    +
      +

    • put watchCosim in working state after time stepping, before changing over to individual data frames

      • +

    • move *.csv files finally into folder /results

      • +
    +
    • +

  • Protect png’s in result folder from being deleted

    • +

  • ospCaseBuilder CLI:

    +
      +

    • inspect mode (–inspect) now adds to the results the attributes of the DefaultExperiment element from the FMU’s modelDescription.xml

      • +
    +
    • +

  • plotting.py:

    +
      +

    • added further exceptions for non-word characters in title strings

      • +
    +
    • +

  • dependencies:

    +
      +

    • ospx now uses dictIO v0.1.1

      • +
    +
    • +
+
+
+
+

0.1.1 - 2022-05-30

+
+

Changed

+
    +

  • case dict file format: Removed ‘root’ element from ‘_environment’ section, as it is obsolete.

    • +
+
+
+

Fixed

+
    +

  • relative paths in the ‘fmu’ element led to a FileNotFound error. This is fixed now.

    • +
+
+
+
+

0.1.0 - 2022-05-28

+
+

Changed

+
    +

  • Major refactoring, introducing classes for the main elements such as FMU, Component, SystemStructure etc.

    • +

  • Simplified imports from namespace ospx. Example:

    +
      +

    • Old (<= v0.0.22):

      +
      from ospx.ospCaseBuilder import OspCaseBuilder
+
      +
      +
      • +

    • New:

      +
      from ospx import OspCaseBuilder
+
      +
      +
      • +
    +
    • +

  • Use new simplified imports from namespace dictIO (using updated version of dictIO package)

    • +

  • Two changes were introduced in the case dict file format:

    +
      +

    1. Connector element: key ‘reference’ changed to ‘variable’:

      +
        +

      • Old (<= v0.0.22):

        +
        connectors
+{
+    difference_input_minuend
+    {
+        reference             difference.IN1;
+        type                  input;
+    }
+
        +
        +
        • +

      • New:

        +
        connectors
+{
+    difference_input_minuend
+    {
+        variable            difference.IN1;
+        type                input;
+    }
+
        +
        +
        • +
      +
      2. +

    2. Connection element: source and target changed from single strings to fully qualified endpoints, providing not only the connector but also the component the connector or variable belongs to:

      +
        +

      • Old (<= v0.0.22):

        +
        connections
+{
+    minuend_to_difference
+    {
+        source                minuend_output;
+        target                difference_input_minuend;
+    }
+
        +
        +
        • +

      • New:

        +
        connections
+{
+    minuend_to_difference
+    {
+        source
+        {
+            component               minuend;
+            connector               minuend_output;
+        }
+        target
+        {
+            component               difference;
+            connector               difference_input_minuend;
+        }
+    }
+
        +
        +
        • +

      • Instead of connector, alternatively also a variable can be referenced in source / target endpoint. Example:

        +
        connections
+{
+    minuend_to_difference
+    {
+        source
+        {
+            component               minuend;
+            variable                constVal.OUT;
+        }
+        target
+        {
+            component               difference;
+            variable                difference.IN1;
+        }
+    }
+
        +
        +
        • +
      +
      3. +
    +
    • +
+
+
+
+

0.0.22 - 2022-05-09

+
    +

  • First public release

    • +
+
+
+

0.0.17 - 2022-02-14

+
+

Added

+
    +

  • Added support for Python 3.10

    • +
+ + +
+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/LICENSE.html b/LICENSE.html new file mode 100644 index 00000000..f60b00ab --- /dev/null +++ b/LICENSE.html @@ -0,0 +1,553 @@ + + + + + + + + + LICENSE - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

LICENSE

+

MIT License

+

Copyright (c) 2024 DNV open source

+

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.

+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/README.html b/README.html new file mode 100644 index 00000000..854c403d --- /dev/null +++ b/README.html @@ -0,0 +1,735 @@ + + + + + + + + + farn - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+

pypi +versions +license +ci +docs

+
+

farn

+

farn is an n-dimensional case generator.

+

Its primary design goal is to parameterize and execute simulation cases. +However, at its core, farn is use-case agnostic and can support a wide spectrum of applications.

+

The name ‘farn’ is inspired by the Barnsley fractal

+

farn

+
    +

  • runs the sampling of the design space (sampling strategies cover fixed, linSpace, uniformLHS)

    • +

  • generates the corresponding case folder structure

    • +

  • copies arbitrary files from a template folder to case folders

    • +

  • creates case specific parameter files in case folders

    • +

  • executes user-defined shell command sets in case folders

    • +

  • builds case specific OSP (co-)simulation files

    • +

  • runs simulation cases as batch process

    • +
+
+

Installation

+
pip install farn
+
+
+

farn requires the following two (sub-)packages:

+
    +

  1. dictIO: foundation package, enabling farn to handle configuration files in dictIO dict file format.

    2. +

  2. ospx: extension package, enabling farn to generate OSP (co-)simulation files.

    3. +
+

However, both get installed automatically with farn (just pip install farn and you’re done).

+
+
+

Usage Example

+

farn provides both an API for use inside Python as well as a CLI for shell execution of core functions.

+

Reading a farnDict file and creating the corresponding case folder structure:

+
from farn import run_farn
+
+run_farn('farnDict', sample=True, generate=True)
+
+
+

The above task can also be invoked from the command line, using the ‘farn’ command line script installed with farn:

+
farn farnDict --sample --generate
+
+
+

For more examples and usage, please refer to farn’s documentation.

+

Further, the farn-demo repository on GitHub is an excellent place for a jumpstart into farn. +Simply clone the farn-demo repository to your local machine and click through the demos and related READMEs, by recommendation in the following sequence:

+
README in root folder -> guides you through installation of farn
+\ospCaseBuilder Demo (see README in ospCaseBuilder folder)
+\farn Demo (see README in farn folder)
+\importSystemStructure  Demo (see README in importSystemStructure folder)
+
+
+
+
+

File Format

+

A farnDict is a file in dictIO dict file format used with farn.

+

For a documentation of the farnDict file format, see File Format in farn’s documentation on GitHub Pages.

+

For a detailed documentation of the dictIO dict file format used by farn, see dictIO’s documentation on GitHub Pages.

+
+
+

Development Setup

+
+

1. Install uv

+

This project uses uv as package manager. +If you haven’t already, install uv, preferably using it’s “Standalone installer” method:
+..on Windows:

+
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+
+

..on MacOS and Linux:

+
curl -LsSf https://astral.sh/uv/install.sh | sh
+
+
+

(see docs.astral.sh/uv for all / alternative installation methods.)

+

Once installed, you can update uv to its latest version, anytime, by running:

+
uv self update
+
+
+
+
+

2. Install Python

+

This project requires Python 3.10 or later.
+If you don’t already have a compatible version installed on your machine, the probably most comfortable way to install Python is through uv:

+
uv python install
+
+
+

This will install the latest stable version of Python into the uv Python directory, i.e. as a uv-managed version of Python.

+

Alternatively, and if you want a standalone version of Python on your machine, you can install Python either via winget:

+
winget install --id Python.Python
+
+
+

or you can download and install Python from the python.org website.

+
+
+

3. Clone the repository

+

Clone the dictIO repository into your local development directory:

+
git clone https://github.com/dnv-opensource/farn path/to/your/dev/farn
+
+
+
+
+

4. Install dependencies

+

Run uv sync to create a virtual environment and install all project dependencies into it:

+
uv sync
+
+
+
+
+

5. (Optional) Install CUDA support

+

Run uv sync with option --extra cuda to in addition install torch with CUDA support:

+
uv sync --extra cuda
+
+
+

Alternatively, you can manually install torch with CUDA support. +Note 1: Do this preferably after running uv sync. That way you ensure a virtual environment exists, which is a prerequisite before you install torch with CUDA support using below uv pip install command.

+

To manually install torch with CUDA support, generate a uv pip install command matching your local machine’s operating system using the wizard on the official PyTorch website. +Note: As we use uv as package manager, remember to replace pip in the command generated by the wizard with uv pip.

+

If you are on Windows, the resulting uv pip install command will most likely look something like this:

+
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
+
+
+

Hint: If you are unsure which cuda version to indicate in above uv pip install .. /cuXXX command, you can use the shell command nvidia-smi on your local system to find out the cuda version supported by the current graphics driver installed on your system. When then generating the uv pip install command with the wizard from the PyTorch website, select the cuda version that matches the major version of what your graphics driver supports (major version must match, minor version may deviate).

+
+
+

6. (Optional) Activate the virtual environment

+

When using uv, there is in almost all cases no longer a need to manually activate the virtual environment.
+uv will find the .venv virtual environment in the working directory or any parent directory, and activate it on the fly whenever you run a command via uv inside your project folder structure:

+
uv run <command>
+
+
+

However, you still can manually activate the virtual environment if needed. +When developing in an IDE, for instance, this can in some cases be necessary depending on your IDE settings. +To manually activate the virtual environment, run one of the “known” legacy commands:
+..on Windows:

+
.venv\Scripts\activate.bat
+
+
+

..on Linux:

+
source .venv/bin/activate
+
+
+
+
+

7. Install pre-commit hooks

+

The .pre-commit-config.yaml file in the project root directory contains a configuration for pre-commit hooks. +To install the pre-commit hooks defined therein in your local git repository, run:

+
uv run pre-commit install
+
+
+

All pre-commit hooks configured in .pre-commit-config.yaml will now run each time you commit changes.

+
+
+

8. Test that the installation works

+

To test that the installation works, run pytest in the project root folder:

+
uv run pytest
+
+
+
+
+
+

Meta

+

Copyright (c) 2024 DNV SE. All rights reserved.

+

Frank Lumpitzsch – @LinkedIn – frank.lumpitzsch@dnv.com

+

Claas Rostock – @LinkedIn – claas.rostock@dnv.com

+

Seunghyeon Yoo – @LinkedIn – seunghyeon.yoo@dnv.com

+

Distributed under the MIT license. See LICENSE for more information.

+

https://github.com/dnv-opensource/farn

+
+
+

Contributing

+
    +

  1. Fork it (https://github.com/dnv-opensource/farn/fork)

    2. +

  2. Create an issue in your GitHub repo

    3. +

  3. Create your branch based on the issue number and type (git checkout -b issue-name)

    4. +

  4. Evaluate and stage the changes you want to commit (git add -i)

    5. +

  5. Commit your changes (git commit -am 'place a descriptive commit message here')

    6. +

  6. Push to the branch (git push origin issue-name)

    7. +

  7. Create a new Pull Request in GitHub

    8. +
+

For your contribution, please make sure you follow the STYLEGUIDE before creating the Pull Request.

+ +
+
+ +
+
+
+ +
+ + +
+
+
+
+ Copyright © 2024, DNV SE. All rights reserved. +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/README_dictIO.html b/README_dictIO.html new file mode 100644 index 00000000..58ff5562 --- /dev/null +++ b/README_dictIO.html @@ -0,0 +1,754 @@ + + + + + + + + + dictIO - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+

pypi +versions +license +ci +docs

+
+

dictIO

+

dictIO is a Python package to read, write and manipulate dictionary text files.

+

It was designed to leverage the versatility of text based dictionary files, or ‘dict files’ in short, while easing their use in Python through seamless support for Python dicts.

+

dictIO supports

+
    +

  • reading and writing Python dicts in dict files.

    • +

  • usage of references and expressions in dict files, dynamically resolved during reading.

    • +

  • usage of cascaded dict files, allowing separation of a case-agnostic configuration dict and its case-specific parameterization: baseDict + paramDict = caseDict

    • +
+

Further, dictIO

+
    +

  • is widely tolerant in reading different flavours (quotes, preserving comments, etc.)

    • +

  • can read and write also JSON, XML and OpenFOAM (with some limitations)

    • +
+
+

Installation

+
pip install dictIO
+
+
+
+
+

Usage Example

+

dictIO’s core class is SDict, a generic data structure for serializable dictionaries.
+SDict inherits from Python’s builtin dict. It can hence be used transparently in any context where a dict or any other MutableMapping type is expected.

+

You can use SDict the same way you use dict. E.g. you can pass a dict literal to its constructor:

+
from dictIO import SDict
+
+my_dict: SDict[str, int] = SDict(
+    {
+        "foo": 1,
+        "bar": 2,
+    }
+)
+
+
+

The simplest way to to dump and load a dict to / from a file, is to use SDict’s dump() and load() instance methods:

+

To dump my_dict to a file, use .dump():

+
my_dict.dump("myDict")
+
+
+

To load the formerly dumped file into a new dict, use .load():

+
my_dict_loaded: SDict[str, int] = SDict().load("myDict")
+
+
+

In cases where you need more control over how dict files are read and written,
+dictIO’s DictReader and DictWriter classes offer this flexibility, while still maintaining a simple and high level API:

+
from dictIO import DictReader, DictWriter
+
+my_dict = DictReader.read('myDict')
+DictWriter.write(my_dict, 'parsed.myDict')
+
+
+

The above example reads a dict file, merges any (sub-)dicts included through #include directives, evaluates expressions contained in the dict, +and finally saves the read and evaluated dict with prefix ‘parsed’ as ‘parsed.myDict’.

+

This sequence of reading, evaluating and writing a dict is also called ‘parsing’ in dictIO. +Because this task is so common, dictIO provides a convenience class for it: +Using DictParser.parse() the above task can be accomplished in one line of code:

+
from dictIO import DictParser
+
+DictParser.parse('myDict')
+
+
+

The parse operation can also be executed from the command line, using the ‘dictParser’ command line script installed with dictIO:

+
dictParser myDict
+
+
+

For more examples and usage, please refer to dictIO’s documentation.

+
+
+

File Format

+

The native file format used by dictIO shares, by intention, some commonalities with the OpenFOAM file format, but is kept simpler and more tolerant to different flavours of string formatting.

+

With some limitations, dictIO supports also reading from and writing to OpenFOAM, Json and XML.

+

For a detailed documentation of the native file format used by dictIO, see File Format in dictIO’s documentation on GitHub Pages.

+
+
+

Development Setup

+
+

1. Install uv

+

This project uses uv as package manager. +If you haven’t already, install uv, preferably using it’s “Standalone installer” method:
+..on Windows:

+
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+
+

..on MacOS and Linux:

+
curl -LsSf https://astral.sh/uv/install.sh | sh
+
+
+

(see docs.astral.sh/uv for all / alternative installation methods.)

+

Once installed, you can update uv to its latest version, anytime, by running:

+
uv self update
+
+
+
+
+

2. Install Python

+

This project requires Python 3.10 or later.
+If you don’t already have a compatible version installed on your machine, the probably most comfortable way to install Python is through uv:

+
uv python install
+
+
+

This will install the latest stable version of Python into the uv Python directory, i.e. as a uv-managed version of Python.

+

Alternatively, and if you want a standalone version of Python on your machine, you can install Python either via winget:

+
winget install --id Python.Python
+
+
+

or you can download and install Python from the python.org website.

+
+
+

3. Clone the repository

+

Clone the dictIO repository into your local development directory:

+
git clone https://github.com/dnv-opensource/dictIO path/to/your/dev/dictIO
+
+
+
+
+

4. Install dependencies

+

Run uv sync to create a virtual environment and install all project dependencies into it:

+
uv sync
+
+
+
+
+

5. (Optional) Activate the virtual environment

+

When using uv, there is in almost all cases no longer a need to manually activate the virtual environment.
+uv will find the .venv virtual environment in the working directory or any parent directory, and activate it on the fly whenever you run a command via uv inside your project folder structure:

+
uv run <command>
+
+
+

However, you still can manually activate the virtual environment if needed. +When developing in an IDE, for instance, this can in some cases be necessary depending on your IDE settings. +To manually activate the virtual environment, run one of the “known” legacy commands:
+..on Windows:

+
.venv\Scripts\activate.bat
+
+
+

..on Linux:

+
source .venv/bin/activate
+
+
+
+
+

6. Install pre-commit hooks

+

The .pre-commit-config.yaml file in the project root directory contains a configuration for pre-commit hooks. +To install the pre-commit hooks defined therein in your local git repository, run:

+
uv run pre-commit install
+
+
+

All pre-commit hooks configured in .pre-commit-config.yaml will now run each time you commit changes.

+
+
+

7. Test that the installation works

+

To test that the installation works, run pytest in the project root folder:

+
uv run pytest
+
+
+
+
+
+

Meta

+

Copyright (c) 2024 DNV SE. All rights reserved.

+

Frank Lumpitzsch - @LinkedIn - frank.lumpitzsch@dnv.com

+

Claas Rostock - @LinkedIn - claas.rostock@dnv.com

+

Seunghyeon Yoo - @LinkedIn - seunghyeon.yoo@dnv.com

+

Distributed under the MIT license. See LICENSE for more information.

+

https://github.com/dnv-opensource/dictIO

+
+
+

Contributing

+
    +

  1. Fork it (https://github.com/dnv-opensource/dictIO/fork)

    2. +

  2. Create an issue in your GitHub repo

    3. +

  3. Create your branch based on the issue number and type (git checkout -b issue-name)

    4. +

  4. Evaluate and stage the changes you want to commit (git add -i)

    5. +

  5. Commit your changes (git commit -am 'place a descriptive commit message here')

    6. +

  6. Push to the branch (git push origin issue-name)

    7. +

  7. Create a new Pull Request in GitHub

    8. +
+

For your contribution, please make sure you follow the STYLEGUIDE before creating the Pull Request.

+ +
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/README_farn.html b/README_farn.html new file mode 100644 index 00000000..189c4841 --- /dev/null +++ b/README_farn.html @@ -0,0 +1,753 @@ + + + + + + + + + farn - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+

pypi +versions +license +ci +docs

+
+

farn

+

farn is an n-dimensional case generator.

+

Its primary design goal is to parameterize and execute simulation cases. +However, at its core, farn is use-case agnostic and can support a wide spectrum of applications.

+

The name ‘farn’ is inspired by the Barnsley fractal

+

farn

+
    +

  • runs the sampling of the design space (sampling strategies cover fixed, linSpace, uniformLHS)

    • +

  • generates the corresponding case folder structure

    • +

  • copies arbitrary files from a template folder to case folders

    • +

  • creates case specific parameter files in case folders

    • +

  • executes user-defined shell command sets in case folders

    • +

  • builds case specific OSP (co-)simulation files

    • +

  • runs simulation cases as batch process

    • +
+
+

Installation

+
pip install farn
+
+
+

farn requires the following two (sub-)packages:

+
    +

  1. dictIO: foundation package, enabling farn to handle configuration files in dictIO dict file format.

    2. +

  2. ospx: extension package, enabling farn to generate OSP (co-)simulation files.

    3. +
+

However, both get installed automatically with farn (just pip install farn and you’re done).

+
+
+

Usage Example

+

farn provides both an API for use inside Python as well as a CLI for shell execution of core functions.

+

Reading a farnDict file and creating the corresponding case folder structure:

+
from farn import run_farn
+
+run_farn('farnDict', sample=True, generate=True)
+
+
+

The above task can also be invoked from the command line, using the ‘farn’ command line script installed with farn:

+
farn farnDict --sample --generate
+
+
+

For more examples and usage, please refer to farn’s documentation.

+

Further, the farn-demo repository on GitHub is an excellent place for a jumpstart into farn. +Simply clone the farn-demo repository to your local machine and click through the demos and related READMEs, by recommendation in the following sequence:

+
README in root folder -> guides you through installation of farn
+\ospCaseBuilder Demo (see README in ospCaseBuilder folder)
+\farn Demo (see README in farn folder)
+\importSystemStructure  Demo (see README in importSystemStructure folder)
+
+
+
+
+

File Format

+

A farnDict is a file in dictIO dict file format used with farn.

+

For a documentation of the farnDict file format, see File Format in farn’s documentation on GitHub Pages.

+

For a detailed documentation of the dictIO dict file format used by farn, see dictIO’s documentation on GitHub Pages.

+
+
+

Development Setup

+
+

1. Install uv

+

This project uses uv as package manager. +If you haven’t already, install uv, preferably using it’s “Standalone installer” method:
+..on Windows:

+
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+
+

..on MacOS and Linux:

+
curl -LsSf https://astral.sh/uv/install.sh | sh
+
+
+

(see docs.astral.sh/uv for all / alternative installation methods.)

+

Once installed, you can update uv to its latest version, anytime, by running:

+
uv self update
+
+
+
+
+

2. Install Python

+

This project requires Python 3.10 or later.
+If you don’t already have a compatible version installed on your machine, the probably most comfortable way to install Python is through uv:

+
uv python install
+
+
+

This will install the latest stable version of Python into the uv Python directory, i.e. as a uv-managed version of Python.

+

Alternatively, and if you want a standalone version of Python on your machine, you can install Python either via winget:

+
winget install --id Python.Python
+
+
+

or you can download and install Python from the python.org website.

+
+
+

3. Clone the repository

+

Clone the dictIO repository into your local development directory:

+
git clone https://github.com/dnv-opensource/farn path/to/your/dev/farn
+
+
+
+
+

4. Install dependencies

+

Run uv sync to create a virtual environment and install all project dependencies into it:

+
uv sync
+
+
+
+
+

5. (Optional) Install CUDA support

+

Run uv sync with option --extra cuda to in addition install torch with CUDA support:

+
uv sync --extra cuda
+
+
+

Alternatively, you can manually install torch with CUDA support. +Note 1: Do this preferably after running uv sync. That way you ensure a virtual environment exists, which is a prerequisite before you install torch with CUDA support using below uv pip install command.

+

To manually install torch with CUDA support, generate a uv pip install command matching your local machine’s operating system using the wizard on the official PyTorch website. +Note: As we use uv as package manager, remember to replace pip in the command generated by the wizard with uv pip.

+

If you are on Windows, the resulting uv pip install command will most likely look something like this:

+
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
+
+
+

Hint: If you are unsure which cuda version to indicate in above uv pip install .. /cuXXX command, you can use the shell command nvidia-smi on your local system to find out the cuda version supported by the current graphics driver installed on your system. When then generating the uv pip install command with the wizard from the PyTorch website, select the cuda version that matches the major version of what your graphics driver supports (major version must match, minor version may deviate).

+
+
+

6. (Optional) Activate the virtual environment

+

When using uv, there is in almost all cases no longer a need to manually activate the virtual environment.
+uv will find the .venv virtual environment in the working directory or any parent directory, and activate it on the fly whenever you run a command via uv inside your project folder structure:

+
uv run <command>
+
+
+

However, you still can manually activate the virtual environment if needed. +When developing in an IDE, for instance, this can in some cases be necessary depending on your IDE settings. +To manually activate the virtual environment, run one of the “known” legacy commands:
+..on Windows:

+
.venv\Scripts\activate.bat
+
+
+

..on Linux:

+
source .venv/bin/activate
+
+
+
+
+

7. Install pre-commit hooks

+

The .pre-commit-config.yaml file in the project root directory contains a configuration for pre-commit hooks. +To install the pre-commit hooks defined therein in your local git repository, run:

+
uv run pre-commit install
+
+
+

All pre-commit hooks configured in .pre-commit-config.yaml will now run each time you commit changes.

+
+
+

8. Test that the installation works

+

To test that the installation works, run pytest in the project root folder:

+
uv run pytest
+
+
+
+
+
+

Meta

+

Copyright (c) 2024 DNV SE. All rights reserved.

+

Frank Lumpitzsch – @LinkedIn – frank.lumpitzsch@dnv.com

+

Claas Rostock – @LinkedIn – claas.rostock@dnv.com

+

Seunghyeon Yoo – @LinkedIn – seunghyeon.yoo@dnv.com

+

Distributed under the MIT license. See LICENSE for more information.

+

https://github.com/dnv-opensource/farn

+
+
+

Contributing

+
    +

  1. Fork it (https://github.com/dnv-opensource/farn/fork)

    2. +

  2. Create an issue in your GitHub repo

    3. +

  3. Create your branch based on the issue number and type (git checkout -b issue-name)

    4. +

  4. Evaluate and stage the changes you want to commit (git add -i)

    5. +

  5. Commit your changes (git commit -am 'place a descriptive commit message here')

    6. +

  6. Push to the branch (git push origin issue-name)

    7. +

  7. Create a new Pull Request in GitHub

    8. +
+

For your contribution, please make sure you follow the STYLEGUIDE before creating the Pull Request.

+ +
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/README_ospx.html b/README_ospx.html new file mode 100644 index 00000000..119047b6 --- /dev/null +++ b/README_ospx.html @@ -0,0 +1,736 @@ + + + + + + + + + ospx - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+

pypi +versions +license +ci +docs

+
+

ospx

+

ospx is an extension package to farn, adding support to build OSP (co-)simulation cases using functional mockup units (FMUs).

+

ospx supports

+
    +

  • building of case-specific OSP (co-)simulation configuration files

    • +

  • watching the progress of cosim, and saving final simulation results as a pandas dataframe.

    • +
+
+

Installation

+
pip install ospx
+
+
+

ospx requires the following (sub-)package:

+
    +

  • dictIO: foundation package, enabling ospx to handle configuration files in dictIO dict file format.

    • +
+

However, dictIO gets installed automatically with ospx.

+
+
+

Usage Example

+

ospx provides both an API for use inside Python as well as a CLI for shell execution of core functions.

+

Reading a caseDict file and building the case-specific OSP (co-)simulation configuration files:

+
from ospx import OspCaseBuilder
+
+OspCaseBuilder.build('caseDict')
+
+
+

The above task can also be invoked from the command line, using the ‘ospCaseBuilder’ command line script installed with ospx:

+
ospCaseBuilder caseDict
+
+
+

For more examples and usage, please refer to ospx’s documentation.

+
+
+

File Format

+

A caseDict is a file in dictIO dict file format used with farn.

+

For a documentation of the caseDict file format, see File Format in ospx’s documentation on GitHub Pages.

+

For a detailed documentation of the dictIO dict file format used by farn, see dictIO’s documentation on GitHub Pages.

+
+
+

Development Setup

+
+

1. Install uv

+

This project uses uv as package manager. +If you haven’t already, install uv, preferably using it’s “Standalone installer” method:
+..on Windows:

+
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+
+

..on MacOS and Linux:

+
curl -LsSf https://astral.sh/uv/install.sh | sh
+
+
+

(see docs.astral.sh/uv for all / alternative installation methods.)

+

Once installed, you can update uv to its latest version, anytime, by running:

+
uv self update
+
+
+
+
+

2. Install Python

+

This project requires Python 3.10 or later.
+If you don’t already have a compatible version installed on your machine, the probably most comfortable way to install Python is through uv:

+
uv python install
+
+
+

This will install the latest stable version of Python into the uv Python directory, i.e. as a uv-managed version of Python.

+

Alternatively, and if you want a standalone version of Python on your machine, you can install Python either via winget:

+
winget install --id Python.Python
+
+
+

or you can download and install Python from the python.org website.

+
+
+

3. Clone the repository

+

Clone the dictIO repository into your local development directory:

+
git clone https://github.com/dnv-opensource/ospx path/to/your/dev/ospx
+
+
+
+
+

4. Install dependencies

+

Run uv sync to create a virtual environment and install all project dependencies into it:

+
uv sync
+
+
+
+
+

5. (Optional) Install CUDA support

+

Run uv sync with option --extra cuda to in addition install torch with CUDA support:

+
uv sync --extra cuda
+
+
+

Alternatively, you can manually install torch with CUDA support. +Note 1: Do this preferably after running uv sync. That way you ensure a virtual environment exists, which is a prerequisite before you install torch with CUDA support using below uv pip install command.

+

To manually install torch with CUDA support, generate a uv pip install command matching your local machine’s operating system using the wizard on the official PyTorch website. +Note: As we use uv as package manager, remember to replace pip in the command generated by the wizard with uv pip.

+

If you are on Windows, the resulting uv pip install command will most likely look something like this:

+
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
+
+
+

Hint: If you are unsure which cuda version to indicate in above uv pip install .. /cuXXX command, you can use the shell command nvidia-smi on your local system to find out the cuda version supported by the current graphics driver installed on your system. When then generating the uv pip install command with the wizard from the PyTorch website, select the cuda version that matches the major version of what your graphics driver supports (major version must match, minor version may deviate).

+
+
+

6. (Optional) Activate the virtual environment

+

When using uv, there is in almost all cases no longer a need to manually activate the virtual environment.
+uv will find the .venv virtual environment in the working directory or any parent directory, and activate it on the fly whenever you run a command via uv inside your project folder structure:

+
uv run <command>
+
+
+

However, you still can manually activate the virtual environment if needed. +When developing in an IDE, for instance, this can in some cases be necessary depending on your IDE settings. +To manually activate the virtual environment, run one of the “known” legacy commands:
+..on Windows:

+
.venv\Scripts\activate.bat
+
+
+

..on Linux:

+
source .venv/bin/activate
+
+
+
+
+

7. Install pre-commit hooks

+

The .pre-commit-config.yaml file in the project root directory contains a configuration for pre-commit hooks. +To install the pre-commit hooks defined therein in your local git repository, run:

+
uv run pre-commit install
+
+
+

All pre-commit hooks configured in .pre-commit-config.yaml will now run each time you commit changes.

+
+
+

8. Test that the installation works

+

To test that the installation works, run pytest in the project root folder:

+
uv run pytest
+
+
+
+
+
+

Meta

+

Copyright (c) 2024 DNV SE. All rights reserved.

+

Frank Lumpitzsch – @LinkedIn – frank.lumpitzsch@dnv.com

+

Claas Rostock – @LinkedIn – claas.rostock@dnv.com

+

Seunghyeon Yoo – @LinkedIn – seunghyeon.yoo@dnv.com

+

Distributed under the MIT license. See LICENSE for more information.

+

https://github.com/dnv-opensource/ospx

+
+
+

Contributing

+
    +

  1. Fork it (https://github.com/dnv-opensource/ospx/fork)

    2. +

  2. Create an issue in your GitHub repo

    3. +

  3. Create your branch based on the issue number and type (git checkout -b issue-name)

    4. +

  4. Evaluate and stage the changes you want to commit (git add -i)

    5. +

  5. Commit your changes (git commit -am 'place a descriptive commit message here')

    6. +

  6. Push to the branch (git push origin issue-name)

    7. +

  7. Create a new Pull Request in GitHub

    8. +
+

For your contribution, please make sure you follow the STYLEGUIDE before creating the Pull Request.

+ +
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/STYLEGUIDE.html b/STYLEGUIDE.html new file mode 100644 index 00000000..8cb5fef2 --- /dev/null +++ b/STYLEGUIDE.html @@ -0,0 +1,990 @@ + + + + + + + + + Style Guide - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Style Guide

+

All code shall be Ruff formatted.

+

References, details as well as examples of bad/good styles and their respective reasoning can be found below.

+
+

References

+ +
+
+

Code Layout

+
    +

  • Use 4 spaces instead of tabs

    • +

  • Maximum line length is 120 characters (not 79 as proposed in PEP-8)

    • +

  • 2 blank lines between classes and functions

    • +

  • 1 blank line within class, between class methods

    • +

  • Use blank lines for logic separation of functionality within functions/methods wherever it is justified

    • +

  • No whitespace adjacent to parentheses, brackets, or braces

    • +
+
    # Bad
+    spam( items[ 1 ], { key1 : arg1, key2 : arg2 }, )
+
+    # Good
+    spam(items[1], {key1: arg1, key2: arg2}, [])
+
+
+
    +

  • Surround operators with single whitespace on either side.

    • +
+
    # Bad
+    x<1
+
+    # Good
+    x == 1
+
+
+
    +

  • Never end your lines with a semicolon, and do not use a semicolon to put two statements on the same line

    • +

  • When branching, always start a new block on a new line

    • +
+
    # Bad
+    if flag: return None
+
+    # Good
+    if flag:
+        return None
+
+
+
    +

  • Similarly to branching, do not write methods on one line in any case:

    • +
+
    # Bad
+    def do_something(self): print("Something")
+
+    # Good
+    def do_something(self):
+        print("Something")
+
+
+
    +

  • Place a class’s __init__ function (the constructor) always at the beginning of the class

    • +
+
+
+

Line Breaks

+
    +

  • If function arguments do not fit into the specified line length, move them to a new line with indentation

    • +
+
    # Bad
+    def long_function_name(var_one, var_two, var_three,
+        var_four):
+        print(var_one)
+
+    # Bad
+    def long_function_name(var_one, var_two, var_three,
+            var_four):
+        print(var_one)
+
+    # Better (but not preferred)
+    def long_function_name(var_one,
+                           var_two,
+                           var_three,
+                           var_four):
+        print(var_one)
+
+    # Good (and preferred)
+    def long_function_name(
+        var_one,
+        var_two,
+        var_three,
+        var_four,
+    ):
+        print(var_one)
+
+
+
    +

  • Move concatenated logical conditions to new lines if the line does not fit the maximum line size. This will help you understand the condition by looking from top to bottom. Poor formatting makes it difficult to read and understand complex predicates.

    • +
+
    # Good
+    if (
+        this_is_one_thing
+        and that_is_another_thing
+        or that_is_third_thing
+        or that_is_yet_another_thing
+        and one_more_thing
+    ):
+        do_something()
+
+
+
    +

  • Where binary operations stretch multiple lines, break lines before the binary operators, not thereafter

    • +
+
    # Bad
+    GDP = (
+        private_consumption +
+        gross_investment +
+        government_investment +
+        government_spending +
+        (exports - imports)
+    )
+
+    # Good
+    GDP = (
+        private_consumption
+        + gross_investment
+        + government_investment
+        + government_spending
+        + (exports - imports)
+    )
+
+
+
    +

  • Chaining methods should be broken up on multiple lines for better readability

    • +
+
    (
+        df.write.format("jdbc")
+        .option("url", "jdbc:postgresql:dbserver")
+        .option("dbtable", "schema.tablename")
+        .option("user", "username")
+        .option("password", "password")
+        .save()
+    )
+
+
+
    +

  • Add a trailing comma to sequences of items when the closing container token ], ), or } does not appear on the same line as the final element

    • +
+
    # Bad
+    y = [
+        0,
+        1,
+        4,
+        6
+    ]
+    z = {
+        'a': 1,
+        'b': 2
+    }
+
+    # Good
+    x = [1, 2, 3]
+
+    # Good
+    y = [
+        0,
+        1,
+        4,
+        6,         <- note the trailing comma
+    ]
+    z = {
+        'a': 1,
+        'b': 2,    <- note the trailing comma
+    }
+
+
+
+
+

String Formatting

+
    +

  • When quoting string literals, use double-quoted strings. When the string itself contains single or double quote characters, however, use the respective other one to avoid backslashes in the string. It improves readability.

    • +

  • Use f-strings to format strings:

    • +
+
    # Bad
+    print("Hello, %s. You are %s years old. You are a %s." % (name, age, profession))
+
+    # Good
+    print(f"Hello, {name}. You are {age} years old. You are a {profession}.")
+
+
+
    +

  • Use multiline strings, not \ , since it gets much more readable.

    • +
+
    raise AttributeError(
+        "Here is a multiline error message with a very long first line "
+        "and a shorter second line."
+    )
+
+
+
+
+

Naming Conventions

+
    +

  • For module names: lowercase . +Long module names can have words separated by underscores (really_long_module_name.py), but this is not required. Try to use the convention of nearby files.

    • +

  • For class names: CamelCase

    • +

  • For methods, functions, variables and attributes: lowercase_with_underscores

    • +

  • For constants: UPPERCASE or UPPERCASE_WITH_UNDERSCORES +(Python does not differentiate between variables and constants. Using UPPERCASE for constants is just a convention, but helps a lot to quickly identify variables meant to serve as constants.)

    • +

  • Implementation-specific private methods and variables will use _single_underscore_prefix

    • +

  • Don’t include the type of a variable in its name. +E.g. use senders instead of sender_list

    • +

  • Names shall be clear about what a variable, class, or function contains or does. If you struggle to come up with a clear name, rethink your architecture: Often, the difficulty in finding a crisp name for something is a hint that separation of responsibilities can be improved. The solution then is less to agree on a name, but to start a round of refactoring: The name you’re seeking often comes naturally then with refactoring to an improved architecture with clear responsibilities. +(see SRP, Single-Responsibilty Principle by Robert C. Martin)

    • +
+
+
+

Named Arguments

+
    +

  • Use named arguments to improve readability and avoid mistakes introduced with future code maintenance

    • +
+
    # Bad
+    urlget("[http://google.com](http://google.com/)", 20)
+
+    # Good
+    urlget("[http://google.com](http://google.com/)", timeout=20)
+
+
+
    +

  • Never use mutable objects as default arguments in Python. If an attribute in a class or a named parameter in a function is of a mutable data type (e.g. a list or dict), never set its default value in the declaration of an object but always set it to None first, and then only later assign the default value in the class’s constructor, or the functions body, respectively. Sounds complicated? If you prefer the shortcut, the examples below are your friend. +If you are interested in the long story including the why‘s, read these discussions on Reddit and Twitter.

    • +
+
    # Bad
+    class Foo:
+        items = []
+
+    # Good
+    class Foo:
+        items = None
+        def __init__(self):
+            self.items = []
+
+
+    # Bad
+    class Foo:
+        def __init__(self, items=[]):
+            self.items = items
+
+    # Good
+    class Foo:
+        def __init__(self, items=None):
+            self.items = items or []
+
+
+    # Bad
+    def some_function(x, y, items=[]):
+        ...
+
+    # Good
+    def some_function(x, y, items=None):
+        items = items or []
+        ...
+
+
+
+
+

Commenting

+
    +

  • First of all, if the code needs comments to clarify its work, you should think about refactoring it. The best comment to code is the code itself.

    • +

  • Describe complex, possibly incomprehensible points and side effects in the comments

    • +

  • Separate # and the comment with one whitespace

    • +
+
    #bad comment
+    # good comment
+
+
+
    +

  • Use inline comments sparsely

    • +

  • Where used, inline comments shall have 2 whitespaces before the # and one whitespace thereafter

    • +
+
    x = y + z  # inline comment
+    str1 = str2 + str3  # another inline comment
+
+
+
    +

  • If a piece of code is poorly understood, mark the piece with a @TODO: tag and your name to support future refactoring:

    • +
+
    def get_ancestors_ids(self):
+        # @TODO: Do a cache reset while saving the category tree. CLAROS, YYYY-MM-DD
+        cache_name = f"{self._meta.model_name}_ancestors_{self.pk}"
+        cached_ids = cache.get(cache_name)
+        if cached_ids:
+            return cached_ids
+
+        ids = [c.pk for c in self.get_ancestors(include_self=True)]
+        cache.set(cache_name, ids, timeout=3600)
+
+        return ids
+
+
+
+
+

Type hints

+
    +

  • Use type hints in function signatures and module-scope variables. This is good documentation and can be used with linters for type checking and error checking. Use them whenever possible.

    • +

  • Use pyi files to type annotate third-party or extension modules.

    • +
+
+
+

Docstrings

+
    +

  • All Docstrings should be written in Numpy format. For a good tutorial on Docstrings, see Documenting Python Code: A Complete Guide

    • +

  • In a Docstring, summarize function/method behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions

    • +

  • Wrap Docstrings with triple double quotes (“””)

    • +

  • The description of the arguments must be indented

    • +
+
    def some_method(name, print=False):
+        """This function does something
+
+        Parameters
+        ----------
+        name : str
+            The name to use
+        print: bool, optional
+            A flag used to print the name to the console, by default False
+
+        Raises
+        ------
+        KeyError
+            If name is not found
+
+        Returns
+        -------
+        int
+            The return code
+        """
+        ...
+        return 0
+
+
+
+
+

Exceptions

+
    +

  • Raise specific exceptions and catch specific exceptions, such as KeyError, ValueError, etc.

    • +

  • Do not raise or catch just Exception, except in rare cases where this is unavoidable, such as a try/except block on the top-level loop of some long-running process. For a good tutorial on why this matters, see The Most Diabolical Python Antipattern.

    • +

  • Minimize the amount of code in a try/except block. The larger the body of the try, +the more likely that an exception will be raised by a line of code that you didn’t expect to raise an exception.

    • +
+
+
+

Imports

+
    +

  • Avoid creating circular imports by importing modules more specialized than the one you are editing

    • +

  • Relative imports are forbidden (PEP-8 only “highly discourages” them). Where absolutely needed, the from future import absolute_import syntax should be used (see PEP-328)

    • +

  • Never use wildcard imports (from <module> import *). Always be explicit about what you’re importing. Namespaces make code easier to read, so use them.

    • +

  • Break long imports using parentheses and indent by 4 spaces. Include the trailing comma after the last import and place the closing bracket on a separate line

    • +
+
    from my_pkg.utils import (
+        some_utility_method_1,
+        some_utility_method_2,
+        some_utility_method_3,
+        some_utility_method_4,
+        some_utility_method_5,
+    )
+
+
+
    +

  • Imports should be written in the following order, separated by a blank line:

    +
      +

    1. build-in modules

      2. +

    2. third-party modules

      3. +

    3. local application/library specific imports

      4. +
    +
    • +
+
    import logging
+    import os
+    import typing as T
+
+    import pandas as pd
+    import numpy as np
+
+    import my_package
+    import my_package.my_module
+    from my_package.my_module import my_function, MyClass
+
+
+
    +

  • Even if a Python file is intended to be used as executable / script file only, it shall still be importable as a module, and its import should not have any side effects. Its main functionality shall hence be in a main() function, so that the code can be imported as a module for testing or being reused in the future:

    • +
+
    def main():
+        ...
+
+    if __name__ == "__main__":
+        main()
+
+
+
+
+

Unit-tests

+
    +

  • Use pytest as the preferred testing framework.

    • +

  • The name of a test shall clearly express what is being tested.

    • +

  • Each test should preferably check only one specific aspect.

    • +
+
    # Bad
+    def test_smth():
+        result = f()
+        assert isinstance(result, list)
+        assert result[0] == 1
+        assert result[1] == 2
+        assert result[2] == 3
+        assert result[3] == 4
+
+    # Good
+    def test_smth_type():
+        result = f()
+        assert isinstance(result, list), "Result should be list"
+
+    def test_smth_values():
+        result = f()
+        assert set(result) == set(expected), f"Result should be {set(expected)}"
+
+
+
+
+

And finally: It is a bad idea to use

+
    +

  • global variables.

    • +

  • iterators where they can be replaced by vectorized operations.

    • +

  • lambda where it is not required.

    • +

  • map and lambda where it can be replaced by a simple list comprehension.

    • +

  • multiple nested maps and lambdas.

    • +

  • nested functions. They are hard to test and debug.

    • +
+
+
+ +
+
+
+ +
+ + +
+
+
+
+ Copyright © 2024, DNV SE. All rights reserved. +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.cpp_dict.CppDict.html b/_autosummary/dictIO.cpp_dict.CppDict.html new file mode 100644 index 00000000..29182974 --- /dev/null +++ b/_autosummary/dictIO.cpp_dict.CppDict.html @@ -0,0 +1,679 @@ + + + + + + + + + CppDict - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

CppDict

+
+
+class dictIO.cpp_dict.CppDict(**kwargs: Any)
+
+class dictIO.cpp_dict.CppDict(arg: Mapping[str, Any], **kwargs: Any)
+
+class dictIO.cpp_dict.CppDict(arg: Iterable[tuple[str, Any]], **kwargs: Any)
+
+class dictIO.cpp_dict.CppDict(arg: str | os.PathLike[str], **kwargs: Any)
+

Bases: SDict[str, Any]

+

Data structure for C++ dictionaries.

+

This class is deprecated and will be removed in 0.5.0. +Use SDict[K, V] instead.

+
+
+__init__(**kwargs: Any) → None
+
+__init__(arg: Mapping[str, Any], **kwargs: Any) → None
+
+__init__(arg: Iterable[tuple[str, Any]], **kwargs: Any) → None
+
+__init__(arg: str | os.PathLike[str], **kwargs: Any) → None
+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

clear()

copy()

Return a shallow copy of the SDict instance.

dump([target_file])

Dump the content of the current SDict instance into a dict file.

find_global_key([query])

Return the global key thread to the first key the value of which matches the passed in query.

fromkeys(iterable[, value])

Create a new SDict instance from the keys of an iterable.

get(key[, default])

Return the value for key if key is in the dictionary, else default.

global_key_exists(global_key)

Check whether the specified global key exists.

include(dict_to_include)

Add an include directive for the passed in dict.

items()

keys()

load(source_file)

Load a dict file into this SDict instance.

merge(other)

Merge the passed in dict into the existing SDict instance.

order_keys()

alpha-numeric sorting of keys, recursively.

pop(k[,d])

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

reduce_scope(scope)

Reduces the dict to the keys defined in scope.

reset()

Reset the dict.

set_global_key(global_key, value)

Set the value for the passed in global key.

setdefault(key[, default])

Insert key with a value of default if key is not in the dictionary.

update([m])

Update top-level keys with the keys from the passed in dict.

values()

+
+

Attributes

+
+ + + + + + + + + + + + + + + + + + +

data

Mimick the data property of the CppDict class from dictIO <= v0.3.4.

name

Return the name of the source file of the SDict instance.

path

Return the path of the source file of the SDict instance.

source_file

Return the source file of the SDict instance.

variables

Returns a dict with all Variables currently registered.

+
+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.cpp_dict.html b/_autosummary/dictIO.cpp_dict.html new file mode 100644 index 00000000..ce559713 --- /dev/null +++ b/_autosummary/dictIO.cpp_dict.html @@ -0,0 +1,550 @@ + + + + + + + + + dictIO.cpp_dict - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.cpp_dict

+

Module dictIO.cppDict.

+

_Note_: Deprecated since 0.4.0. +Module dictIO.cppDict and class CppDict will be removed in 0.5.0. +Use module dictIO.dict and class SDict instead.

+

Classes

+
+ + + + + + +

CppDict()

Data structure for C++ dictionaries.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.dict.SDict.html b/_autosummary/dictIO.dict.SDict.html new file mode 100644 index 00000000..b61a4649 --- /dev/null +++ b/_autosummary/dictIO.dict.SDict.html @@ -0,0 +1,997 @@ + + + + + + + + + SDict - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

SDict

+
+
+class dictIO.dict.SDict(**kwargs: V)
+
+class dictIO.dict.SDict(arg: Mapping[K, V], **kwargs: V)
+
+class dictIO.dict.SDict(arg: Iterable[tuple[K, V]], **kwargs: V)
+
+class dictIO.dict.SDict(arg: str | PathLike[str], **kwargs: V)
+

Bases: dict[K, V]

+

Generic data structure for serializable dictionaries. Core class in dictIO.

+

SDict inherits from dict. It can hence be used transparently in any context +where a dict or any other MutableMapping type is expected.

+
+
+__init__(**kwargs: V) → None
+
+__init__(arg: Mapping[K, V], **kwargs: V) → None
+
+__init__(arg: Iterable[tuple[K, V]], **kwargs: V) → None
+
+__init__(arg: str | PathLike[str], **kwargs: V) → None
+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

clear()

copy()

Return a shallow copy of the SDict instance.

dump([target_file])

Dump the content of the current SDict instance into a dict file.

find_global_key([query])

Return the global key thread to the first key the value of which matches the passed in query.

fromkeys()

Create a new SDict instance from the keys of an iterable.

get(key[, default])

Return the value for key if key is in the dictionary, else default.

global_key_exists(global_key)

Check whether the specified global key exists.

include(dict_to_include)

Add an include directive for the passed in dict.

items()

keys()

load(source_file)

Load a dict file into this SDict instance.

merge(other)

Merge the passed in dict into the existing SDict instance.

order_keys()

alpha-numeric sorting of keys, recursively.

pop(k[,d])

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

reduce_scope(scope)

Reduces the dict to the keys defined in scope.

reset()

Reset the dict.

set_global_key(global_key, value)

Set the value for the passed in global key.

setdefault(key[, default])

Insert key with a value of default if key is not in the dictionary.

update()

Update top-level keys with the keys from the passed in dict.

values()

+
+

Attributes

+
+ + + + + + + + + + + + + + + + + + +

data

Mimick the data property of the CppDict class from dictIO <= v0.3.4.

name

Return the name of the source file of the SDict instance.

path

Return the path of the source file of the SDict instance.

source_file

Return the source file of the SDict instance.

variables

Returns a dict with all Variables currently registered.

+
+
+
+copy() → SDict[K, V]
+

Return a shallow copy of the SDict instance.

+
+
Returns:
+

shallow copy of the SDict instance

+
+
Return type:
+

SDict[K, V]

+
+
+
+ +
+
+dump(target_file: str | PathLike[str] | None = None) → Path
+

Dump the content of the current SDict instance into a dict file.

+

Following file formats are supported and interpreted through target_file’s file ending: +no file ending -> dictIO native dict file +‘.cpp’ -> dictIO native dict file +‘.foam’ -> Foam dictionary file +‘.json’ -> Json dictionary file +‘.xml’ -> XML file

+
+
Parameters:
+

target_file (Union[str, os.PathLike[str], None], optional) – target dict file name, by default None

+
+
Returns:
+

target dict file

+
+
Return type:
+

Path

+
+
Raises:
+

ValueError – if target_file was not specified while the current SDict instance has no source file set + (and hence the target file cannot be inferred).

+
+
+
+ +
+
+find_global_key(query: str = '') → list[K | int] | None
+

Return the global key thread to the first key the value of which matches the passed in query.

+

Function works recursively on nested dicts and is non-greedy: The key of the first match is returned. +Return value is a sequence of keys: The ‘global key thread’. +It represents the sequence of keys that one needs to traverse downwards +in order to arrive at the target key found.

+
+
Parameters:
+

query (str, optional) – query string for the value to search for by default ‘’

+
+
Returns:
+

global key thread to the first key the value of which matches the passed in query, if found. Otherwise None.

+
+
Return type:
+

list[K | int] | None

+
+
+
+ +
+
+classmethod fromkeys(iterable: Iterable[_K], value: None = None) → SDict[_K, Any | None]
+
+classmethod fromkeys(iterable: Iterable[_K], value: _V) → SDict[_K, _V]
+

Create a new SDict instance from the keys of an iterable.

+
+
Parameters:
+
    +

  • iterable (Iterable[_K]) – An iterable with keys

    • +

  • value (_V | None, optional) – The value to be assigned to the passed in keys, by default None

    • +
+
+
Returns:
+

The created SDict instance.

+
+
Return type:
+

SDict[_K, _V] | SDict[_K, Any | None]

+
+
+
+ +
+
+global_key_exists(global_key: MutableSequence[K | int]) → bool
+

Check whether the specified global key exists.

+
+
Parameters:
+

global_key (MutableSequence[K | int]) – global key the existence of which is checked

+
+
Returns:
+

True if the specified global key exists, otherwise False

+
+
Return type:
+

bool

+
+
+
+ +
+
+include(dict_to_include: SDict[_K, _V]) → None
+

Add an include directive for the passed in dict.

+
+
Parameters:
+

dict_to_include (SDict) – The dict to be included via an include directive

+
+
Raises:
+
    +

  • AttributeError – If dict_to_include.source_file is None

    • +

  • ValueError – If no relative path in between the current dict and the included dict can be resolved

    • +
+
+
+
+ +
+
+load(source_file: str | PathLike[str]) → SDict[K, V]
+

Load a dict file into this SDict instance.

+

Reads a dict file and loads its content into the current SDict instance. +The content of the current SDict instance will be overwritten.

+

Following file formats are supported and interpreted through source_file’s file ending: +no file ending -> dictIO native dict file +‘.cpp’ -> dictIO native dict file +‘.foam’ -> Foam dictionary file +‘.json’ -> Json dictionary file +‘.xml’ -> XML file

+
+
Parameters:
+

source_file (Union[str, os.PathLike[str]]) – dict file to be loaded

+
+
Returns:
+

self

+
+
Return type:
+

SDict[K, V]

+
+
Raises:
+

FileNotFoundError – if source_file does not exist

+
+
+
+ +
+
+merge(other: Mapping[K, V]) → None
+

Merge the passed in dict into the existing SDict instance.

+

In contrast to update(), merge() works recursively. That is, it does not simply substitute top-level keys but +recursively merges (potentially nested) content from the passed in dict into the existing. +This prevents nested keys from being deleted. +Further, existing keys will NOT be overwritten.

+
+
Parameters:
+

other (Mapping[K, V]) – dict to be merged

+
+
+
+ +
+
+order_keys() → None
+

alpha-numeric sorting of keys, recursively.

+
+ +
+
+reduce_scope(scope: MutableSequence[K]) → None
+

Reduces the dict to the keys defined in scope.

+
+
Parameters:
+

scope (MutableSequence[K]) – scope the dict shall be reduced to

+
+
+
+ +
+
+reset() → None
+

Reset the dict.

+

Removes all items from the dict.

+
+ +
+
+set_global_key(global_key: MutableSequence[K | int], value: V) → None
+

Set the value for the passed in global key.

+

The global key thread is traversed downwards until arrival at the target key, +the value of which is then set.

+
+
Parameters:
+
    +

  • global_key (MutableSequence[K | int]) – list of keys defining the global key thread to the target key (such as returned by method find_global_key())

    • +

  • value (V) – value the target key shall be set to

    • +
+
+
+
+ +
+
+update(m: Mapping[K, V], **kwargs: V) → None
+
+update(m: Iterable[tuple[K, V]], **kwargs: V) → None
+
+update(**kwargs: V) → None
+

Update top-level keys with the keys from the passed in dict.

+

Overrides the update() method of UserDict base class in order to include also SDict +class attributes in the update.

+

If a key already exists, it will be substituted by the key from the passed in dict. +In order to not substitute top-level keys but recursively merge (potentially nested) content +from passed in dict into the existing, use merge() instead.

+

Note:

+

The behaviour of update() corresponds with default mode ‘-w’ in the dictParser command line interface.

+

The behaviour of merge() corresponds with mode ‘-a’ in the dictParser command line interface. +See also CLI Documentation.

+
+
Parameters:
+
    +

  • m (Mapping[K, V] | Iterable[tuple[K, V]] | None) – dict containing the keys to be updated and its new values

    • +

  • **kwargs (V) – optional keyword arguments. These will be passed on to the update() method of the parent class.

    • +
+
+
+
+ +
+
+property data: dict[K, V]
+

Mimick the data property of the CppDict class from dictIO <= v0.3.4.

+

Mimicks the data property of the deprecated CppDict class to maintain +backward compatibility. This property is deprecated and will be removed with v0.5.0.

+
+
Returns:
+

the content of the SDict instance

+
+
Return type:
+

dict[K, V]

+
+
+
+ +
+
+property name: str
+

Return the name of the source file of the SDict instance.

+
+
Returns:
+

name of the source file of the SDict instance

+
+
Return type:
+

str

+
+
+
+ +
+
+property path: Path
+

Return the path of the source file of the SDict instance.

+
+
Returns:
+

path of the source file of the SDict instance

+
+
Return type:
+

Path

+
+
+
+ +
+
+property source_file: Path | None
+

Return the source file of the SDict instance.

+
+
Returns:
+

source file of the SDict instance

+
+
Return type:
+

Path or None

+
+
+
+ +
+
+property variables: dict[str, V]
+

Returns a dict with all Variables currently registered.

+
+
Returns:
+

dict of all Variables currently registered.

+
+
Return type:
+

Dict[str, V]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.dict.html b/_autosummary/dictIO.dict.html new file mode 100644 index 00000000..5d49fd9d --- /dev/null +++ b/_autosummary/dictIO.dict.html @@ -0,0 +1,547 @@ + + + + + + + + + dictIO.dict - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.dict

+

SDict class definition.

+

Classes

+
+ + + + + + +

SDict()

Generic data structure for serializable dictionaries.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.dict_parser.DictParser.html b/_autosummary/dictIO.dict_parser.DictParser.html new file mode 100644 index 00000000..973f2adc --- /dev/null +++ b/_autosummary/dictIO.dict_parser.DictParser.html @@ -0,0 +1,622 @@ + + + + + + + + + DictParser - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

DictParser

+
+
+class dictIO.dict_parser.DictParser
+

Bases: object

+

Parser for dictionaries in dictIO native file format, as well as JSON and XML.

+

DictParser is a convenience class. +DictParser.parse() combines the operations of DictReader.read() and DictWriter.write() .

+
+
+__init__() → None
+
+ +

Methods

+
+ + + + + + + + + +

__init__()

parse(source_file, *[, includes, mode, ...])

Parse a dictionary file and save it with prefix 'parsed.'.

+
+
+
+static parse(source_file: str | PathLike[str], *, includes: bool = True, mode: str = 'w', order: bool = False, comments: bool = True, scope: MutableSequence[Any] | None = None, output: str | None = None) → SDict[Any, Any] | None
+

Parse a dictionary file and save it with prefix ‘parsed.’.

+

DictParser.parse() combines the otherwise atomic operations +of DictReader.read() and DictWriter.write() in one chunk:

+

1: parsed_dict = DictReader.read(source_file)

+

2: DictWriter.write(parsed_dict, target_file)

+

The parsed dict is saved with prefix ‘parsed.’ +Example: Parsing source file ‘xyz’ will result in parsed file ‘parsed.xyz’ being generated.

+

The parsed dict will by default be written in dictIO’s native file format. +Optionally, output format can be changed to JSON, XML and OpenFOAM.

+
+
Parameters:
+
    +

  • source_file (Union[str, os.PathLike[str]]) – dict file to be parsed

    • +

  • includes (bool, optional) – merge sub-dicts being referenced through #include directives, by default True

    • +

  • mode (str, optional) – append to output file (‘a’) or overwrite output file (‘w’), by default ‘w’

    • +

  • order (bool, optional) – sort the parsed dict, by default False

    • +

  • comments (bool, optional) – writes comments to output file, by default True

    • +

  • scope (MutableSequence[str], optional) – scope the dict will be reduced to after parsing, by default None

    • +

  • output (str, optional) – format of the output file. Choices are ‘cpp’, ‘foam’, ‘xml’ and ‘json’., by default None

    • +
+
+
Returns:
+

the parsed dict

+
+
Return type:
+

Union[SDict, None]

+
+
Raises:
+

FileNotFoundError – if source_file does not exist

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.dict_parser.html b/_autosummary/dictIO.dict_parser.html new file mode 100644 index 00000000..9a14bf01 --- /dev/null +++ b/_autosummary/dictIO.dict_parser.html @@ -0,0 +1,547 @@ + + + + + + + + + dictIO.dict_parser - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.dict_parser

+

DictParser class for parsing and translating dictionaries from and to dictIO native file format, as well as JSON and XML.

+

Classes

+
+ + + + + + +

DictParser()

Parser for dictionaries in dictIO native file format, as well as JSON and XML.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.dict_reader.DictReader.html b/_autosummary/dictIO.dict_reader.DictReader.html new file mode 100644 index 00000000..40c6a943 --- /dev/null +++ b/_autosummary/dictIO.dict_reader.DictReader.html @@ -0,0 +1,619 @@ + + + + + + + + + DictReader - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

DictReader

+
+
+class dictIO.dict_reader.DictReader
+

Bases: object

+

Reader for dictionaries in dictIO native file format, as well as JSON and XML.

+
+
+__init__() → None
+
+ +

Methods

+
+ + + + + + + + + +

__init__()

read(source_file, *[, includes, order, ...])

Read a dictionary file in dictIO native file format, as well as JSON and XML.

+
+
+
+static read(source_file: str | PathLike[str], *, includes: bool = True, order: bool = False, comments: bool = True, scope: MutableSequence[Any] | None = None, parser: Parser | None = None) → SDict[Any, Any]
+

Read a dictionary file in dictIO native file format, as well as JSON and XML.

+

Reads a dict file, parses it and transforms its content into a dictIO dict object (SDict). +Following file formats are supported and interpreted through source_file’s file ending: +no file ending -> dictIO native dict file +‘.cpp’ -> dictIO native dict file +‘.foam’ -> Foam dictionary file +‘.json’ -> Json dictionary file +‘.xml’ -> XML file +Return type is in all cases SDict

+
+
Parameters:
+
    +

  • source_file (Union[str, os.PathLike[str]]) – dict file to be read

    • +

  • includes (bool, optional) – merge sub-dicts being referenced through #include directives, by default True

    • +

  • order (bool, optional) – sort the read dict, by default False

    • +

  • comments (bool, optional) – reads comments from source file, by default True

    • +

  • scope (MutableSequence[str], optional) – scope the dict will be reduced to after reading, by default None

    • +

  • parser (Parser, optional) – Parser object to be used, by default None

    • +
+
+
Returns:
+

the read dict

+
+
Return type:
+

SDict[Any, Any]

+
+
Raises:
+

FileNotFoundError – if source_file does not exist

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.dict_reader.html b/_autosummary/dictIO.dict_reader.html new file mode 100644 index 00000000..eeb0a5f6 --- /dev/null +++ b/_autosummary/dictIO.dict_reader.html @@ -0,0 +1,547 @@ + + + + + + + + + dictIO.dict_reader - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.dict_reader

+

DictReader class for reading dictionaries in dictIO native file format, as well as JSON and XML.

+

Classes

+
+ + + + + + +

DictReader()

Reader for dictionaries in dictIO native file format, as well as JSON and XML.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.dict_writer.DictWriter.html b/_autosummary/dictIO.dict_writer.DictWriter.html new file mode 100644 index 00000000..e110fce6 --- /dev/null +++ b/_autosummary/dictIO.dict_writer.DictWriter.html @@ -0,0 +1,612 @@ + + + + + + + + + DictWriter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

DictWriter

+
+
+class dictIO.dict_writer.DictWriter
+

Bases: object

+

Writer for dictionaries in dictIO native file format, as well as JSON, XML and OpenFoam.

+
+
+__init__() → None
+
+ +

Methods

+
+ + + + + + + + + +

__init__()

write(source_dict[, target_file, mode, ...])

Write a dictionary file in dictIO native file format, as well as JSON, XML and OpenFoam.

+
+
+
+static write(source_dict: MutableMapping[K, V], target_file: str | PathLike[str] | None = None, mode: str = 'a', *, order: bool = False, formatter: Formatter | None = None) → None
+

Write a dictionary file in dictIO native file format, as well as JSON, XML and OpenFoam.

+

Writes a dictIO dict (parameter source_dict of type SDict) to target_file. +Following file formats are supported and interpreted through target_file’s file ending: +no file ending -> dictIO native dict file +‘.cpp’ -> dictIO native dict file +‘.foam’ -> Foam dictionary file +‘.json’ -> Json dictionary file +‘.xml’ -> XML file +Following modes are supported: +mode = ‘a’: append to target file. If the existing file contains a dictionary, write() will append the new dict +to the existing through merging. This is the default behaviour. +mode = ‘w’: overwrite target file. The existing file will be overwritten.

+
+
Parameters:
+
    +

  • source_dict (MutableMapping[K, V]) – source dict

    • +

  • target_file (str | os.PathLike[str] | None, optional) – target dict file name, by default None

    • +

  • mode (str, optional) – append to target file (‘a’) or overwrite target file (‘w’), by default ‘a’

    • +

  • order (bool, optional) – if True, the dict will be sorted before writing, by default False

    • +

  • formatter (Formatter | None, optional) – formatter to be used, by default None

    • +
+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.dict_writer.html b/_autosummary/dictIO.dict_writer.html new file mode 100644 index 00000000..b147afc8 --- /dev/null +++ b/_autosummary/dictIO.dict_writer.html @@ -0,0 +1,600 @@ + + + + + + + + + dictIO.dict_writer - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.dict_writer

+

DictWriter class for writing dictionaries in dictIO native file format, as well as JSON and XML.

+

Functions

+
+ + + + + + +

create_target_file_name(source_file[, ...])

Create a well defined target file name.

+
+

Classes

+
+ + + + + + +

DictWriter()

Writer for dictionaries in dictIO native file format, as well as JSON, XML and OpenFoam.

+
+
+
+dictIO.dict_writer.create_target_file_name(source_file: str | PathLike[str], prefix: str | None = None, scope: MutableSequence[Any] | None = None, output: str | None = None) → Path
+

Create a well defined target file name.

+

Helper function to create a target file name based on the source file name, +a prefix, a scope and an output format.

+
+
Parameters:
+
    +

  • source_file (Union[str, os.PathLike[str]]) – source dict file

    • +

  • prefix (Union[str, None], optional) – prefix to be used, by default None

    • +

  • scope (MutableSequence[Any] | None, optional) – scope to be reflected in the target file name, by default None

    • +

  • output (Union[str, None], optional) – format of the target dict file. Choices are ‘cpp’, ‘foam’, ‘xml’ and ‘json’, by default None

    • +
+
+
Returns:
+

target dict file name

+
+
Return type:
+

Path

+
+
+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.formatter.FoamFormatter.html b/_autosummary/dictIO.formatter.FoamFormatter.html new file mode 100644 index 00000000..888d03ab --- /dev/null +++ b/_autosummary/dictIO.formatter.FoamFormatter.html @@ -0,0 +1,750 @@ + + + + + + + + + FoamFormatter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

FoamFormatter

+
+
+class dictIO.formatter.FoamFormatter
+

Bases: NativeFormatter

+

Formatter to serialize a dict into a string in OpenFOAM dictionary format.

+
+
+__init__() → None
+

Define default configuration for FoamFormatter.

+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

Define default configuration for FoamFormatter.

add_double_quotes(arg)

Add double quotes to a string.

add_single_quotes(arg)

Add single quotes to a string.

format_bool(arg)

Format a boolean.

format_dict(arg[, tab_len, level, sep, ...])

Format a dict or list object.

format_empty_string(arg)

Format an empty string.

format_expression_string(arg)

Format an expression.

format_float(arg)

Format a floating point number.

format_int(arg)

Format an integer.

format_key(arg)

Format a key.

format_multi_word_string(arg)

Format a multi word string.

format_none()

Format None.

format_reference_string(arg)

Format a reference.

format_single_word_string(arg)

Format a single word string.

format_string(arg)

Format a string.

format_string_with_nested_string(arg)

Format a string that contains a nested string.

format_value(arg)

Format a single value.

format_values(arg)

Format multiple values.

get_formatter([target_file])

Return a Formatter instance matching the type of the target file to be formatted (factory method).

insert_block_comments(s_dict, s)

Insert back all block comments.

insert_includes(s_dict, s)

Insert back all include directives.

insert_line_comments(s_dict, s)

Insert back all line directives.

make_default_block_comment([block_comment])

Create the default block comment (header) for files in OpenFOAM dictionary format.

remove_trailing_spaces(s)

Remove trailing spaces from all lines.

to_string(arg)

Create a string representation of the passed in dict in OpenFOAM dictionary format.

+
+
+
+format_empty_string(arg: str) → str
+

Format an empty string.

+
+
Parameters:
+

arg (str) – the empty string to be formatted

+
+
Returns:
+

the formatted empty string

+
+
Return type:
+

str

+
+
+
+ +
+
+format_expression_string(arg: str) → str
+

Format an expression.

+
+
Parameters:
+

arg (str) – the expression to be formatted

+
+
Returns:
+

the formatted expression

+
+
Return type:
+

str

+
+
+
+ +
+
+format_multi_word_string(arg: str) → str
+

Format a multi word string.

+
+
Parameters:
+

arg (str) – the multi word string to be formatted

+
+
Returns:
+

the formatted multi word string

+
+
Return type:
+

str

+
+
+
+ +
+
+format_string_with_nested_string(arg: str) → str
+

Format a string that contains a nested string.

+
+
Parameters:
+

arg (str) – the string with a nested string to be formatted

+
+
Returns:
+

the formatted string with a nested string

+
+
Return type:
+

str

+
+
+
+ +
+
+make_default_block_comment(block_comment: str = '') → str
+

Create the default block comment (header) for files in OpenFOAM dictionary format.

+
+ +
+
+to_string(arg: MutableMapping[K, V]) → str
+

Create a string representation of the passed in dict in OpenFOAM dictionary format.

+
+
Parameters:
+

arg (MutableMapping[K, V]) – dict to be formatted

+
+
Returns:
+

string representation of the dict in OpenFOAM dictionary format

+
+
Return type:
+

str

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.formatter.Formatter.html b/_autosummary/dictIO.formatter.Formatter.html new file mode 100644 index 00000000..6485658a --- /dev/null +++ b/_autosummary/dictIO.formatter.Formatter.html @@ -0,0 +1,989 @@ + + + + + + + + + Formatter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Formatter

+
+
+class dictIO.formatter.Formatter
+

Bases: object

+

Abstract Base Class for formatters.

+

Formatters serialize a dict into a string applying a specific format.

+
+
+__init__() → None
+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

add_double_quotes(arg)

Add double quotes to a string.

add_single_quotes(arg)

Add single quotes to a string.

format_bool(arg)

Format a boolean.

format_empty_string(arg)

Format an empty string.

format_expression_string(arg)

Format an expression.

format_float(arg)

Format a floating point number.

format_int(arg)

Format an integer.

format_key(arg)

Format a key.

format_multi_word_string(arg)

Format a multi word string.

format_none()

Format None value.

format_reference_string(arg)

Format a reference.

format_single_word_string(arg)

Format a single word string.

format_string(arg)

Format a string.

format_string_with_nested_string(arg)

Format a string that contains a nested string.

format_value()

Format a single value.

format_values()

Format multiple values.

get_formatter([target_file])

Return a Formatter instance matching the type of the target file to be formatted (factory method).

to_string(arg)

Create a string representation of the passed in dict.

+
+
+
+add_double_quotes(arg: str) → str
+

Add double quotes to a string.

+

Leading and trailing double quotes will added to the passed in string +(i.e. it will be wrapped in double quotes). +Note: Call this base class method from any specific Formatter implementation +to easily add double quotes to a string when formatting.

+
+
Parameters:
+

arg (str) – the string to be wrapped in double quotes

+
+
Returns:
+

the string wrapped in double quotes

+
+
Return type:
+

str

+
+
+
+ +
+
+add_single_quotes(arg: str) → str
+

Add single quotes to a string.

+

Leading and trailing single quotes will added to the passed in string +(i.e. it will be wrapped in single quotes). +Note: Call this base class method from any specific Formatter implementation +to easily add single quotes to a string when formatting.

+
+
Parameters:
+

arg (str) – the string to be wrapped in single quotes

+
+
Returns:
+

the string wrapped in single quotes

+
+
Return type:
+

str

+
+
+
+ +
+
+format_bool(arg: bool) → str
+

Format a boolean.

+

Note: Override this method for specific formatting of booleans when implementing a Formatter.

+
+
Parameters:
+

arg (bool) – the boolean value to be formatted

+
+
Returns:
+

the formatted string representation of the passed in boolean value

+
+
Return type:
+

str

+
+
+
+ +
+
+format_empty_string(arg: str) → str
+

Format an empty string.

+

Note: Override this method for specific formatting of empty strings when implementing a Formatter.

+
+
Parameters:
+

arg (str) – the empty string to be formatted

+
+
Returns:
+

the formatted empty string

+
+
Return type:
+

str

+
+
+
+ +
+
+format_expression_string(arg: str) → str
+

Format an expression.

+

Note: Override this method for specific formatting of expressions when implementing a Formatter.

+
+
Parameters:
+

arg (str) – the expression to be formatted

+
+
Returns:
+

the formatted expression

+
+
Return type:
+

str

+
+
+
+ +
+
+format_float(arg: float) → str
+

Format a floating point number.

+

Note: Override this method for specific formatting of floating point numbers when implementing a Formatter.

+
+
Parameters:
+

arg (float) – the float to be formatted

+
+
Returns:
+

the formatted string representation of the passed in float

+
+
Return type:
+

str

+
+
+
+ +
+
+format_int(arg: int) → str
+

Format an integer.

+

Note: Override this method for specific formatting of integers when implementing a Formatter.

+
+
Parameters:
+

arg (int) – the int to be formatted

+
+
Returns:
+

the formatted string representation of the passed in int

+
+
Return type:
+

str

+
+
+
+ +
+
+format_key(arg: Hashable) → str
+

Format a key.

+

Formats a key of type TKey = str | int

+
+
Parameters:
+

arg (TKey) – the key to be formatted

+
+
Returns:
+

the formatted string representation of the passed in key

+
+
Return type:
+

str

+
+
+
+ +
+
+format_multi_word_string(arg: str) → str
+

Format a multi word string.

+

Note: Override this method for specific formatting of multi word strings when implementing a Formatter.

+
+
Parameters:
+

arg (str) – the multi word string to be formatted

+
+
Returns:
+

the formatted multi word string

+
+
Return type:
+

str

+
+
+
+ +
+
+format_none() → str
+

Format None value.

+

Note: Override this method for specific formatting of None when implementing a Formatter.

+
+
Returns:
+

the formatted string representation of None

+
+
Return type:
+

str

+
+
+
+ +
+
+format_reference_string(arg: str) → str
+

Format a reference.

+

Note: Override this method for specific formatting of references when implementing a Formatter.

+
+
Parameters:
+

arg (str) – the reference to be formatted

+
+
Returns:
+

the formatted reference

+
+
Return type:
+

str

+
+
+
+ +
+
+format_single_word_string(arg: str) → str
+

Format a single word string.

+

Note: Override this method for specific formatting of single word strings when implementing a Formatter.

+
+
Parameters:
+

arg (str) – the single word string to be formatted

+
+
Returns:
+

the formatted single word string

+
+
Return type:
+

str

+
+
+
+ +
+
+format_string(arg: str) → str
+

Format a string.

+
+
Parameters:
+

arg (str) – the string to be formatted

+
+
Returns:
+

the formatted string

+
+
Return type:
+

str

+
+
+
+ +
+
+format_string_with_nested_string(arg: str) → str
+

Format a string that contains a nested string.

+

Note: Override this method for specific formatting of strings with nested strings when implementing a Formatter.

+
+
Parameters:
+

arg (str) – the string with a nested string to be formatted

+
+
Returns:
+

the formatted string with a nested string

+
+
Return type:
+

str

+
+
+
+ +
+
+format_value(arg: str | int | float | bool | None) → str
+
+format_value(arg: Any) → str
+

Format a single value.

+

Formats a single value of type TSingleValue = str | int | float | bool | Path | None

+
+
Parameters:
+

arg (V) – the value to be formatted

+
+
Returns:
+

the formatted string representation of the passed in value, +if value is of TSingleValue type = str | int | float | bool | Path | None. +For all other types, the method will, as fallback, call and return str(arg). +It is hence guaranteed that a string gets returned.

+
+
Return type:
+

str

+
+
+
+ +
+
+format_values(arg: M) → M
+
+format_values(arg: S) → S
+

Format multiple values.

+

Formats all values inside a dict or list. +The function traverses the passed in dict or list recursively +so that all values in also nested dicts and lists get formatted. +A copy of the passed in dict or list is returned with all values formatted. +(The original dict or list is not modified.)

+
+
Parameters:
+

arg (MutableMapping[K, V] | MutableSequence[V]) – the dict or list containing the values to be formatted.

+
+
Returns:
+

a copy of the passed in dict or list, with all values formatted.

+
+
Return type:
+

MutableMapping[K, V] | MutableSequence[V]

+
+
+
+ +
+
+classmethod get_formatter(target_file: Path | None = None) → Formatter
+

Return a Formatter instance matching the type of the target file to be formatted (factory method).

+
+
Parameters:
+

target_file (Path, optional) – name of the target file to be formatted, by default None

+
+
Returns:
+

specific Formatter instance matching the target file type to be formatted

+
+
Return type:
+

Formatter

+
+
+
+ +
+
+to_string(arg: MutableMapping[K, V]) → str
+

Create a string representation of the passed in dict.

+

Note: Override this method when implementing a specific Formatter.

+
+
Parameters:
+

arg (Union[MutableMapping[K, V]]) – dict to be formatted

+
+
Returns:
+

string representation of the dict

+
+
Return type:
+

str

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.formatter.JsonFormatter.html b/_autosummary/dictIO.formatter.JsonFormatter.html new file mode 100644 index 00000000..0c996c63 --- /dev/null +++ b/_autosummary/dictIO.formatter.JsonFormatter.html @@ -0,0 +1,663 @@ + + + + + + + + + JsonFormatter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

JsonFormatter

+
+
+class dictIO.formatter.JsonFormatter
+

Bases: Formatter

+

Formatter to serialize a dict into a string in JSON dictionary format.

+
+
+__init__() → None
+

Define default configuration for JsonFormatter.

+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

Define default configuration for JsonFormatter.

add_double_quotes(arg)

Add double quotes to a string.

add_single_quotes(arg)

Add single quotes to a string.

format_bool(arg)

Format a boolean.

format_empty_string(arg)

Format an empty string.

format_expression_string(arg)

Format an expression.

format_float(arg)

Format a floating point number.

format_int(arg)

Format an integer.

format_key(arg)

Format a key.

format_multi_word_string(arg)

Format a multi word string.

format_none()

Format None value.

format_reference_string(arg)

Format a reference.

format_single_word_string(arg)

Format a single word string.

format_string(arg)

Format a string.

format_string_with_nested_string(arg)

Format a string that contains a nested string.

format_value(arg)

Format a single value.

format_values(arg)

Format multiple values.

get_formatter([target_file])

Return a Formatter instance matching the type of the target file to be formatted (factory method).

insert_includes(s_dict, s)

Insert back all include directives.

to_string(arg)

Create a string representation of the passed in dict in JSON dictionary format.

+
+
+
+insert_includes(s_dict: SDict[K, V], s: str) → str
+

Insert back all include directives.

+
+ +
+
+to_string(arg: MutableMapping[K, V]) → str
+

Create a string representation of the passed in dict in JSON dictionary format.

+
+
Parameters:
+

arg (MutableMapping[K, V]) – dict to be formatted

+
+
Returns:
+

string representation of the dict in JSON dictionary format

+
+
Return type:
+

str

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.formatter.NativeFormatter.html b/_autosummary/dictIO.formatter.NativeFormatter.html new file mode 100644 index 00000000..198a7e10 --- /dev/null +++ b/_autosummary/dictIO.formatter.NativeFormatter.html @@ -0,0 +1,823 @@ + + + + + + + + + NativeFormatter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

NativeFormatter

+
+
+class dictIO.formatter.NativeFormatter
+

Bases: Formatter

+

Formatter to serialize a dict into a string in dictIO native file format.

+
+
+__init__() → None
+

Define default configuration for NativeFormatter.

+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

Define default configuration for NativeFormatter.

add_double_quotes(arg)

Add double quotes to a string.

add_single_quotes(arg)

Add single quotes to a string.

format_bool(arg)

Format a boolean.

format_dict(arg[, tab_len, level, sep, ...])

Format a dict or list object.

format_empty_string(arg)

Format an empty string.

format_expression_string(arg)

Format an expression.

format_float(arg)

Format a floating point number.

format_int(arg)

Format an integer.

format_key(arg)

Format a key.

format_multi_word_string(arg)

Format a multi word string.

format_none()

Format None.

format_reference_string(arg)

Format a reference.

format_single_word_string(arg)

Format a single word string.

format_string(arg)

Format a string.

format_string_with_nested_string(arg)

Format a string that contains a nested string.

format_value(arg)

Format a single value.

format_values(arg)

Format multiple values.

get_formatter([target_file])

Return a Formatter instance matching the type of the target file to be formatted (factory method).

insert_block_comments(s_dict, s)

Insert back all block comments.

insert_includes(s_dict, s)

Insert back all include directives.

insert_line_comments(s_dict, s)

Insert back all line directives.

make_default_block_comment([block_comment])

Create the default block comment (header) for files in dictIO native file format.

remove_trailing_spaces(s)

Remove trailing spaces from all lines.

to_string(arg)

Create a string representation of the passed in dict in dictIO native file format.

+
+
+
+format_bool(arg: bool) → str
+

Format a boolean.

+
+
Parameters:
+

arg (bool) – the boolean value to be formatted

+
+
Returns:
+

the formatted string representation of the passed in boolean value

+
+
Return type:
+

str

+
+
+
+ +
+
+format_dict(arg: MutableMapping[Any, Any] | MutableSequence[Any] | Any, tab_len: int = 4, level: int = 0, sep: str = ' ', items_per_line: int = 10, end: str = '\n', ancestry: type[MutableMapping[Any, Any] | MutableSequence[Any]] = MutableMapping) → str
+

Format a dict or list object.

+
+ +
+
+format_empty_string(arg: str) → str
+

Format an empty string.

+
+
Parameters:
+

arg (str) – the empty string to be formatted

+
+
Returns:
+

the formatted empty string

+
+
Return type:
+

str

+
+
+
+ +
+
+format_expression_string(arg: str) → str
+

Format an expression.

+
+
Parameters:
+

arg (str) – the expression to be formatted

+
+
Returns:
+

the formatted expression

+
+
Return type:
+

str

+
+
+
+ +
+
+format_multi_word_string(arg: str) → str
+

Format a multi word string.

+
+
Parameters:
+

arg (str) – the multi word string to be formatted

+
+
Returns:
+

the formatted multi word string

+
+
Return type:
+

str

+
+
+
+ +
+
+format_none() → str
+

Format None.

+
+
Returns:
+

the formatted string representation of None

+
+
Return type:
+

str

+
+
+
+ +
+
+format_string_with_nested_string(arg: str) → str
+

Format a string that contains a nested string.

+
+
Parameters:
+

arg (str) – the string with a nested string to be formatted

+
+
Returns:
+

the formatted string with a nested string

+
+
Return type:
+

str

+
+
+
+ +
+
+insert_block_comments(s_dict: SDict[K, V], s: str) → str
+

Insert back all block comments.

+

Replaces all BLOCKCOMMENT placeholders in s with the actual block_comments saved in dict +str s is expected to contain the SDict’s block_content containing block comment placeholders +to substitute (BLOCKCOMMENT… BLOCKCOMMENT…)

+
+ +
+
+insert_includes(s_dict: SDict[K, V], s: str) → str
+

Insert back all include directives.

+
+ +
+
+insert_line_comments(s_dict: SDict[K, V], s: str) → str
+

Insert back all line directives.

+
+ +
+
+make_default_block_comment(block_comment: str = '') → str
+

Create the default block comment (header) for files in dictIO native file format.

+
+ +
+
+remove_trailing_spaces(s: str) → str
+

Remove trailing spaces from all lines.

+

Reads all lines from the passed in string, removes trailing spaces from each line and +returns a new string with trailing spaces removed.

+
+ +
+
+to_string(arg: MutableMapping[K, V]) → str
+

Create a string representation of the passed in dict in dictIO native file format.

+
+
Parameters:
+

arg (MutableMapping[K, V]) – dict to be formatted

+
+
Returns:
+

string representation of the dict in dictIO native file format

+
+
Return type:
+

str

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.formatter.XmlFormatter.html b/_autosummary/dictIO.formatter.XmlFormatter.html new file mode 100644 index 00000000..5b0ed057 --- /dev/null +++ b/_autosummary/dictIO.formatter.XmlFormatter.html @@ -0,0 +1,696 @@ + + + + + + + + + XmlFormatter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

XmlFormatter

+
+
+class dictIO.formatter.XmlFormatter(*, omit_prefix: bool = True, integrate_attributes: bool = True, remove_node_numbering: bool = True)
+

Bases: Formatter

+

Formatter to serialize a dict into a string in xml format.

+
+
Defaults:

namespaces: ‘https://www.w3.org/2009/XMLSchema/XMLSchema.xsd’ n +root tag: ‘NOTSPECIFIED’ n +root attributes: None n +indent: 4

+
+
+

Defaults can be overwritten by adding a subdict ‘_xmlOpts’ to dict, +containing ‘_nameSpaces’, ‘_rootTag’, ‘_rootAttributes’.

+

Adding a subdict ‘_attributes’ to a subdict inside dict causes the XmlFormatter to write xml attributes. +In contrast to xml, there are some specialties in dict format what need to be customized:

+
+
property | in xml | sibling in dict |
+
:———– | :—————– | :————– |
+
general name | root tag | the file name is the ‘root tag’ and hence the name of the dict |
+
name | element name (tag) | sub-dict name (has to be unique) |
+
+
| (multiple occurrences allowed due to attributes) | |
+
+
attributes | as required | attributes need to be provided in a separate subdict “_attributes” to take action |
+
style | namespace(s) | style guide, no namespaces (ns can be provided in a subdict “_xmlOpts”) |
+
+
+
+__init__(*, omit_prefix: bool = True, integrate_attributes: bool = True, remove_node_numbering: bool = True) → None
+

Define default configuration for XmlFormatter.

+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__(*[, omit_prefix, ...])

Define default configuration for XmlFormatter.

add_double_quotes(arg)

Add double quotes to a string.

add_single_quotes(arg)

Add single quotes to a string.

format_bool(arg)

Format a boolean.

format_empty_string(arg)

Format an empty string.

format_expression_string(arg)

Format an expression.

format_float(arg)

Format a floating point number.

format_int(arg)

Format an integer.

format_key(arg)

Format a key.

format_multi_word_string(arg)

Format a multi word string.

format_none()

Format None value.

format_reference_string(arg)

Format a reference.

format_single_word_string(arg)

Format a single word string.

format_string(arg)

Format a string.

format_string_with_nested_string(arg)

Format a string that contains a nested string.

format_value(arg)

Format a single value.

format_values(arg)

Format multiple values.

get_formatter([target_file])

Return a Formatter instance matching the type of the target file to be formatted (factory method).

populate_into_element(element, arg[, xsd_uri])

Populate arg into the XML element node.

to_string(arg)

Create a string representation of the passed in dict in XML format.

+
+
+
+populate_into_element(element: Element, arg: MutableMapping[Any, Any] | MutableSequence[Any] | Any, xsd_uri: str | None = None) → None
+

Populate arg into the XML element node.

+

If arg is a dict or list, method will call itself recursively until all nested content within the dict or list +is populated into nested elements, eventually creating an XML dom.

+
+
Parameters:
+
    +

  • element (Element) – element which will be populated

    • +

  • arg (MutableMapping[Any, Any] | MutableSequence[Any] | Any) – value to be populated into the element

    • +

  • xsd_uri (str, optional) – xsd uri, by default None

    • +
+
+
+
+ +
+
+to_string(arg: MutableMapping[K, V]) → str
+

Create a string representation of the passed in dict in XML format.

+
+
Parameters:
+

arg (MutableMapping[K, V]) – dict to be formatted

+
+
Returns:
+

string representation of the dict in XML format

+
+
Return type:
+

str

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.formatter.html b/_autosummary/dictIO.formatter.html new file mode 100644 index 00000000..17b7ea19 --- /dev/null +++ b/_autosummary/dictIO.formatter.html @@ -0,0 +1,559 @@ + + + + + + + + + dictIO.formatter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.formatter

+

Formatter for different dictionary file formats.

+

Classes

+
+ + + + + + + + + + + + + + + + + + +

FoamFormatter()

Formatter to serialize a dict into a string in OpenFOAM dictionary format.

Formatter()

Abstract Base Class for formatters.

JsonFormatter()

Formatter to serialize a dict into a string in JSON dictionary format.

NativeFormatter()

Formatter to serialize a dict into a string in dictIO native file format.

XmlFormatter(*[, omit_prefix, ...])

Formatter to serialize a dict into a string in xml format.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.parser.FoamParser.html b/_autosummary/dictIO.parser.FoamParser.html new file mode 100644 index 00000000..d97b1e64 --- /dev/null +++ b/_autosummary/dictIO.parser.FoamParser.html @@ -0,0 +1,627 @@ + + + + + + + + + FoamParser - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

FoamParser

+
+
+class dictIO.parser.FoamParser
+

Bases: NativeParser

+

Parser to deserialize a string in OpenFOAM dictionary format into a SDict.

+
+
+__init__() → None
+

Define default configuration for FoamParser.

+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

Define default configuration for FoamParser.

get_parser([source_file])

Return a Parser instance matching the type of the source file to be parsed (factory method).

parse_file(source_file[, target_dict, comments])

Parse a file and deserialize it into a dict.

parse_key(arg)

Parse a single key.

parse_string(string, target_dict, *[, comments])

Parse a string in OpenFOAM dictionary format and deserialize it into a SDict.

parse_value(arg)

Parse a single value.

parse_values(arg)

Parse multiple values.

remove_quotes_from_string(arg, *[, all_quotes])

Remove quotes from a string.

remove_quotes_from_strings(arg)

Remove quotes from multiple strings.

+
+
+
+parse_string(string: str, target_dict: SDict[K, V], *, comments: bool = True) → SDict[K, V]
+

Parse a string in OpenFOAM dictionary format and deserialize it into a SDict.

+
+
Parameters:
+
    +

  • string (str) – the string to be parsed (i.e. the content of the file that had been read using parse_file())

    • +

  • target_dict (SDict[K, V]) – the target dict the parsed dict file shall be merged into

    • +

  • comments (bool, optional) – reads comments, by default True

    • +
+
+
Returns:
+

the parsed dict

+
+
Return type:
+

SDict[K, V]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.parser.JsonParser.html b/_autosummary/dictIO.parser.JsonParser.html new file mode 100644 index 00000000..dabe9ced --- /dev/null +++ b/_autosummary/dictIO.parser.JsonParser.html @@ -0,0 +1,627 @@ + + + + + + + + + JsonParser - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

JsonParser

+
+
+class dictIO.parser.JsonParser
+

Bases: Parser

+

Parser to deserialize a string in JSON dictionary format into a SDict.

+
+
+__init__() → None
+

Define default configuration for JsonParser.

+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

Define default configuration for JsonParser.

get_parser([source_file])

Return a Parser instance matching the type of the source file to be parsed (factory method).

parse_file(source_file[, target_dict, comments])

Parse a file and deserialize it into a dict.

parse_key(arg)

Parse a single key.

parse_string(string, target_dict, *[, comments])

Parse a string in JSON dictionary format and deserialize it into a SDict.

parse_value(arg)

Parse a single value.

parse_values(arg)

Parse multiple values.

remove_quotes_from_string(arg, *[, all_quotes])

Remove quotes from a string.

remove_quotes_from_strings(arg)

Remove quotes from multiple strings.

+
+
+
+parse_string(string: str, target_dict: SDict[K, V], *, comments: bool = True) → SDict[K, V]
+

Parse a string in JSON dictionary format and deserialize it into a SDict.

+
+
Parameters:
+
    +

  • string (str) – the string to be parsed (i.e. the content of the file that had been read using parse_file())

    • +

  • target_dict (SDict[K, V]) – the target dict the parsed dict file shall be merged into

    • +

  • comments (bool, optional) – reads comments, by default True

    • +
+
+
Returns:
+

the parsed dict

+
+
Return type:
+

SDict[K, V]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.parser.NativeParser.html b/_autosummary/dictIO.parser.NativeParser.html new file mode 100644 index 00000000..a6ef44e8 --- /dev/null +++ b/_autosummary/dictIO.parser.NativeParser.html @@ -0,0 +1,627 @@ + + + + + + + + + NativeParser - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

NativeParser

+
+
+class dictIO.parser.NativeParser
+

Bases: Parser

+

Parser to deserialize a string in dictIO native file format into a SDict.

+
+
+__init__() → None
+

Define default configuration for NativeParser.

+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

Define default configuration for NativeParser.

get_parser([source_file])

Return a Parser instance matching the type of the source file to be parsed (factory method).

parse_file(source_file[, target_dict, comments])

Parse a file and deserialize it into a dict.

parse_key(arg)

Parse a single key.

parse_string(string, target_dict, *[, comments])

Parse a string in dictIO native file format and deserialize it into a SDict.

parse_value(arg)

Parse a single value.

parse_values(arg)

Parse multiple values.

remove_quotes_from_string(arg, *[, all_quotes])

Remove quotes from a string.

remove_quotes_from_strings(arg)

Remove quotes from multiple strings.

+
+
+
+parse_string(string: str, target_dict: SDict[K, V], *, comments: bool = True) → SDict[K, V]
+

Parse a string in dictIO native file format and deserialize it into a SDict.

+
+
Parameters:
+
    +

  • string (str) – the string to be parsed (i.e. the content of the file that had been read using parse_file())

    • +

  • target_dict (SDict) – the target dict the parsed dict file shall be merged into

    • +

  • comments (bool, optional) – reads comments, by default True

    • +
+
+
Returns:
+

the parsed dict

+
+
Return type:
+

SDict

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.parser.Parser.html b/_autosummary/dictIO.parser.Parser.html new file mode 100644 index 00000000..9d1fd686 --- /dev/null +++ b/_autosummary/dictIO.parser.Parser.html @@ -0,0 +1,770 @@ + + + + + + + + + Parser - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Parser

+
+
+class dictIO.parser.Parser
+

Bases: object

+

Base Class for parsers.

+

Parsers deserialize a string into a SDict. +Subclasses of Parser implement parsing of different, specifically formatted strings (see also Formatters).

+
+
+__init__() → None
+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__()

get_parser([source_file])

Return a Parser instance matching the type of the source file to be parsed (factory method).

parse_file(source_file[, target_dict, comments])

Parse a file and deserialize it into a dict.

parse_key(arg)

Parse a single key.

parse_string(string, target_dict, *[, comments])

Parse a string and deserialize it into a SDict.

parse_value(arg)

Parse a single value.

parse_values(arg)

Parse multiple values.

remove_quotes_from_string(arg, *[, all_quotes])

Remove quotes from a string.

remove_quotes_from_strings(arg)

Remove quotes from multiple strings.

+
+
+
+classmethod get_parser(source_file: Path | None = None) → Parser
+

Return a Parser instance matching the type of the source file to be parsed (factory method).

+
+
Parameters:
+

source_file (Path, optional) – name of the source file to be parsed, by default None

+
+
Returns:
+

specific Parser instance matching the source file type to be parsed

+
+
Return type:
+

Parser

+
+
+
+ +
+
+parse_file(source_file: str | os.PathLike[str], target_dict: SDict[K, V] | None = None, *, comments: bool = True) → SDict[K, V]
+

Parse a file and deserialize it into a dict.

+
+
Parameters:
+
    +

  • source_file (Union[str, os.PathLike[str]]) – name of the dict file to be parsed

    • +

  • target_dict (SDict[K, V], optional) – the target dict the parsed dict file shall be merged into, by default None

    • +

  • comments (bool, optional) – reads comments from source file, by default True

    • +
+
+
Returns:
+

the parsed dict

+
+
Return type:
+

SDict[K, V]

+
+
Raises:
+

FileNotFoundError – if source_file does not exist

+
+
+
+ +
+
+parse_key(arg: str) → Hashable
+

Parse a single key.

+

Parses a single key and casts it to its native type (TKey = str | int).

+
+
Parameters:
+

arg (str) – the value to be parsed

+
+
Returns:
+

the value casted to its native type (TKey = str | int)

+
+
Return type:
+

TKey

+
+
+
+ +
+
+parse_string(string: str, target_dict: SDict[K, V], *, comments: bool = True) → SDict[K, V]
+

Parse a string and deserialize it into a SDict.

+

Note: Override this method when implementing a specific Parser.

+
+
Parameters:
+
    +

  • string (str) – the string to be parsed (i.e. the content of the file that had been read using parse_file())

    • +

  • target_dict (SDict[K, V]) – the target dict the parsed dict file shall be merged into

    • +

  • comments (bool, optional) – reads comments, by default True

    • +
+
+
Returns:
+

the parsed dict

+
+
Return type:
+

SDict[K, V]

+
+
+
+ +
+
+parse_value(arg: Any) → str | int | float | bool | None
+

Parse a single value.

+

Parses a single value and casts it to its native type (TSingleValue = str | int | float | bool | None).

+
+
Parameters:
+

arg (TValue) – the value to be parsed

+
+
Returns:
+

the value casted to its native type (TSingleValue = str | int | float | bool | None)

+
+
Return type:
+

TSingleValue

+
+
+
+ +
+
+parse_values(arg: MutableMapping[K, V] | MutableSequence[V]) → None
+

Parse multiple values.

+

Parses all values inside a dict or list and casts them to its native types (str, int, float, bool or None). +The function traverses the passed in dict or list recursively +so that all values in also nested dicts and lists are parsed.

+
+
Parameters:
+

arg (Union[MutableMapping[K, V], MutableSequence[V]]) – the dict or list containing the values to be parsed and casted to its native types +(str, int, float, bool or None)

+
+
+
+ +
+
+static remove_quotes_from_string(arg: str, *, all_quotes: bool = False) → str
+

Remove quotes from a string.

+

Removes quotes (single and double quotes) from the string object passed in.

+
+
Parameters:
+
    +

  • arg (str) – the string with quotes

    • +

  • all_quotes (bool, optional) – if true, all quotes inside the string will be removed (not only leading and trailing quotes), +by default False

    • +
+
+
Returns:
+

the string with quotes being removed

+
+
Return type:
+

str

+
+
+
+ +
+
+static remove_quotes_from_strings(arg: M | S) → M | S
+

Remove quotes from multiple strings.

+

Removes quotes (single and double quotes) from all string objects inside a dict or list. +The function traverses the passed in dict or list recursively +so that all strings in also nested dicts and lists are processed.

+
+
Parameters:
+

arg (MutableMapping[K, V] | MutableSequence[V]) – the dict or list containing strings the quotes in which shall be removed

+
+
Returns:
+

the original dict or list, yet with quotes in all strings being removed

+
+
Return type:
+

MutableMapping[K, V] | MutableSequence[V]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.parser.XmlParser.html b/_autosummary/dictIO.parser.XmlParser.html new file mode 100644 index 00000000..a5430242 --- /dev/null +++ b/_autosummary/dictIO.parser.XmlParser.html @@ -0,0 +1,627 @@ + + + + + + + + + XmlParser - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

XmlParser

+
+
+class dictIO.parser.XmlParser(*, add_node_numbering: bool = True)
+

Bases: Parser

+

Parser to deserialize a string in XML format into a SDict.

+
+
+__init__(*, add_node_numbering: bool = True) → None
+

Define default configuration for XmlParser.

+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__(*[, add_node_numbering])

Define default configuration for XmlParser.

get_parser([source_file])

Return a Parser instance matching the type of the source file to be parsed (factory method).

parse_file(source_file[, target_dict, comments])

Parse a file and deserialize it into a dict.

parse_key(arg)

Parse a single key.

parse_string(string, target_dict, *[, comments])

Parse a string in XML format and deserialize it into a SDict.

parse_value(arg)

Parse a single value.

parse_values(arg)

Parse multiple values.

remove_quotes_from_string(arg, *[, all_quotes])

Remove quotes from a string.

remove_quotes_from_strings(arg)

Remove quotes from multiple strings.

+
+
+
+parse_string(string: str, target_dict: SDict[K, V], *, comments: bool = True) → SDict[K, V]
+

Parse a string in XML format and deserialize it into a SDict.

+
+
Parameters:
+
    +

  • string (str) – the string to be parsed (i.e. the content of the file that had been read using parse_file())

    • +

  • target_dict (SDict[K, V]) – the target dict the parsed dict file shall be merged into

    • +

  • comments (bool, optional) – reads comments, by default True

    • +
+
+
Returns:
+

the parsed dict

+
+
Return type:
+

SDict[K, V]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.parser.html b/_autosummary/dictIO.parser.html new file mode 100644 index 00000000..4166fed6 --- /dev/null +++ b/_autosummary/dictIO.parser.html @@ -0,0 +1,559 @@ + + + + + + + + + dictIO.parser - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.parser

+

Parsers for different dictionary file formats.

+

Classes

+
+ + + + + + + + + + + + + + + + + + +

FoamParser()

Parser to deserialize a string in OpenFOAM dictionary format into a SDict.

JsonParser()

Parser to deserialize a string in JSON dictionary format into a SDict.

NativeParser()

Parser to deserialize a string in dictIO native file format into a SDict.

Parser()

Base Class for parsers.

XmlParser(*[, add_node_numbering])

Parser to deserialize a string in XML format into a SDict.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.types.html b/_autosummary/dictIO.types.html new file mode 100644 index 00000000..6ad85abd --- /dev/null +++ b/_autosummary/dictIO.types.html @@ -0,0 +1,537 @@ + + + + + + + + + dictIO.types - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.types

+

Type aliases and generic type variables for the dictIO package.

+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.utils.counter.BorgCounter.html b/_autosummary/dictIO.utils.counter.BorgCounter.html new file mode 100644 index 00000000..982d6708 --- /dev/null +++ b/_autosummary/dictIO.utils.counter.BorgCounter.html @@ -0,0 +1,610 @@ + + + + + + + + + BorgCounter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

BorgCounter

+
+
+class dictIO.utils.counter.BorgCounter
+

Bases: object

+

A class that implements a static global counter.

+

Instances of this class all share the same global counter. +This is used in DictReader class to ensure that multiple instances +of SDict do not generate conflicting IDs for placeholder strings +(as would be the case otherwise when merging included dicts).

+
+
+__init__() → None
+
+ +

Methods

+
+ + + + + + + + + +

__init__()

reset()

Reset the BorgCounter.

+
+

Attributes

+
+ + + + + + +

Borg

+
+
+
+static reset() → None
+

Reset the BorgCounter.

+
+ +
+
+Borg: ClassVar[dict[str, int]] = {'theCount': -1}
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.utils.counter.DejaVue.html b/_autosummary/dictIO.utils.counter.DejaVue.html new file mode 100644 index 00000000..5da782e8 --- /dev/null +++ b/_autosummary/dictIO.utils.counter.DejaVue.html @@ -0,0 +1,625 @@ + + + + + + + + + DejaVue - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

DejaVue

+
+
+class dictIO.utils.counter.DejaVue
+

Bases: object

+

A class that implements a static global registry of strings.

+
+
+__init__() → None
+
+ +

Methods

+
+ + + + + + + + + +

__init__()

reset()

Reset DejaVue.

+
+

Attributes

+
+ + + + + + + + + +

djv

strings

Return a list with all strings currently registered with DejaVue.

+
+
+
+reset() → None
+

Reset DejaVue.

+

Clears the list of registered strings.

+
+ +
+
+djv: ClassVar[dict[str, list[str]]] = {'strings': []}
+
+ +
+
+property strings: list[str]
+

Return a list with all strings currently registered with DejaVue.

+
+
Returns:
+

list with all strings currently registered with DejaVue.

+
+
Return type:
+

List[str]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.utils.counter.Indenter.html b/_autosummary/dictIO.utils.counter.Indenter.html new file mode 100644 index 00000000..d0b2f7f2 --- /dev/null +++ b/_autosummary/dictIO.utils.counter.Indenter.html @@ -0,0 +1,628 @@ + + + + + + + + + Indenter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Indenter

+
+
+class dictIO.utils.counter.Indenter(tab_size: int = 4, tab_char: str = ' ')
+

Bases: object

+

A class that implements a static global indentation.

+

Instances of this class all share the same global indentation. +This is used in logger class to ensure a readable message hirarchy.

+
+
+__init__(tab_size: int = 4, tab_char: str = ' ') → None
+
+ +

Methods

+
+ + + + + + + + + + + + + + + +

__init__([tab_size, tab_char])

decr([decrease])

Decreas the Indent.

incr([increase])

Increase the Indent.

reset()

Reset the Indent.

+
+

Attributes

+
+ + + + + + +

Ind

+
+
+
+static decr(decrease: int = 1) → None
+

Decreas the Indent.

+
+ +
+
+static incr(increase: int = 1) → None
+

Increase the Indent.

+
+ +
+
+static reset() → None
+

Reset the Indent.

+
+ +
+
+Ind: dict[str, Any] = {'Indent': 0, 'TabChar': ' ', 'TabSize': 4}
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.utils.counter.html b/_autosummary/dictIO.utils.counter.html new file mode 100644 index 00000000..1f562001 --- /dev/null +++ b/_autosummary/dictIO.utils.counter.html @@ -0,0 +1,553 @@ + + + + + + + + + dictIO.utils.counter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.utils.counter

+

Singleton classes for global counter, indentation and string registry.

+

Classes

+
+ + + + + + + + + + + + +

BorgCounter()

A class that implements a static global counter.

DejaVue()

A class that implements a static global registry of strings.

Indenter([tab_size, tab_char])

A class that implements a static global indentation.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.utils.dict.html b/_autosummary/dictIO.utils.dict.html new file mode 100644 index 00000000..4185b599 --- /dev/null +++ b/_autosummary/dictIO.utils.dict.html @@ -0,0 +1,650 @@ + + + + + + + + + dictIO.utils.dict - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.utils.dict

+

Utility functions for working with dictionaries.

+

Functions

+
+ + + + + + + + + + + + + + + +

find_global_key(arg[, query])

Return the global key thread to the first key the value of which matches the passed in query.

global_key_exists(dict_in, global_key)

Check whether the specified global key exists in the passed in dict.

order_keys(arg)

alpha-numeric sorting of keys, recursively.

set_global_key(arg, global_key, value)

Set the value for the passed in global key.

+
+
+
+dictIO.utils.dict.find_global_key(arg: MutableMapping[K, V] | MutableSequence[V], query: str = '') → list[K | int] | None
+

Return the global key thread to the first key the value of which matches the passed in query.

+
+
Parameters:
+
    +

  • arg (Union[MutableMapping[K, V], MutableSequence[V]]) – dict to search in for the queried value

    • +

  • query (str, optional) – query string for the value to search for, by default ‘’

    • +
+
+
Returns:
+

global key thread to the first key the value of which matches the passed in query, if found. Otherwise None.

+
+
Return type:
+

list[K | int] | None

+
+
+
+ +
+
+dictIO.utils.dict.global_key_exists(dict_in: MutableMapping[K, V], global_key: MutableSequence[K | int]) → bool
+

Check whether the specified global key exists in the passed in dict.

+
+
Parameters:
+
    +

  • dict_in (MutableMapping[K, V]) – dict to check for existence of the specified global key

    • +

  • global_key (MutableSequence[K | int]) – global key the existence of which is checked in the passed in dict

    • +
+
+
Returns:
+

True if the specified global key exists, otherwise False

+
+
Return type:
+

bool

+
+
+
+ +
+
+dictIO.utils.dict.order_keys(arg: M) → M
+

alpha-numeric sorting of keys, recursively.

+
+
Parameters:
+

arg (_MT) – MutableMapping, the keys of which shall be sorted.

+
+
Returns:
+

the passed in MutableMapping, with keys sorted. The same instance is returned.

+
+
Return type:
+

_MT

+
+
+
+ +
+
+dictIO.utils.dict.set_global_key(arg: MutableMapping[K, V], global_key: Sequence[K | int], value: V) → None
+

Set the value for the passed in global key.

+
+
Parameters:
+
    +

  • arg (MutableMapping[K, V]) – dict the target key in which shall be set

    • +

  • global_key (MutableSequence[K | int]) – list of keys defining the global key thread to the target key (such as returned by method find_global_key())

    • +

  • value (V) – value the target key shall be set to

    • +
+
+
+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.utils.html b/_autosummary/dictIO.utils.html new file mode 100644 index 00000000..3c6695fa --- /dev/null +++ b/_autosummary/dictIO.utils.html @@ -0,0 +1,559 @@ + + + + + + + + + dictIO.utils - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.utils

+

Utility functions for dictionary I/O operations.

+

Modules

+
+ + + + + + + + + + + + + + + + + + +

counter

Singleton classes for global counter, indentation and string registry.

dict

Utility functions for working with dictionaries.

logging

Functions to configure logging for the application.

path

Utility functions for working with paths.

strings

Utility functions for string manipulation.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.utils.logging.html b/_autosummary/dictIO.utils.logging.html new file mode 100644 index 00000000..2b260d0e --- /dev/null +++ b/_autosummary/dictIO.utils.logging.html @@ -0,0 +1,587 @@ + + + + + + + + + dictIO.utils.logging - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.utils.logging

+

Functions to configure logging for the application.

+

Functions

+
+ + + + + + +

configure_logging([log_level_console, ...])

Configure logging for the application, allowing for both console and file logging.

+
+
+
+dictIO.utils.logging.configure_logging(log_level_console: str = 'WARNING', log_file: Path | None = None, log_level_file: str = 'WARNING') → None
+

Configure logging for the application, allowing for both console and file logging.

+

Sets the log levels and formats for the output, ensuring that logs are captured as specified.

+
+
Parameters:
+
    +

  • log_level_console (str, optional) – log level for console output, by default “WARNING”

    • +

  • log_file (Path | None, optional) – log file to be used. If None, file logging is disabled. by default None

    • +

  • log_level_file (str, optional) – log level for file output, by default “WARNING”

    • +
+
+
Raises:
+

TypeError – if an invalid value for log_level_console or log_level_file is passed

+
+
+

Examples

+

configure_logging(log_level_console=”INFO”, log_file=Path(“app.log”), log_level_file=”DEBUG”)

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.utils.path.html b/_autosummary/dictIO.utils.path.html new file mode 100644 index 00000000..4793ada2 --- /dev/null +++ b/_autosummary/dictIO.utils.path.html @@ -0,0 +1,613 @@ + + + + + + + + + dictIO.utils.path - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.utils.path

+

Utility functions for working with paths.

+

Functions

+
+ + + + + + + + + +

highest_common_root_folder(paths)

Return the highest common root folder among the passed in paths.

relative_path(from_path, to_path)

Return the relative path from one path to another.

+
+
+
+dictIO.utils.path.highest_common_root_folder(paths: Sequence[Path]) → Path
+

Return the highest common root folder among the passed in paths.

+
+
Parameters:
+

paths (Sequence[Path]) – A sequence of path objects. Can be files or folders, or both.

+
+
Returns:
+

The highest common root folder among the passed in paths.

+
+
Return type:
+

Path

+
+
Raises:
+

ValueError – If argument ‘paths’ is empty or if the passed in paths do not share a common root folder.

+
+
+
+ +
+
+dictIO.utils.path.relative_path(from_path: Path, to_path: Path) → Path
+

Return the relative path from one path to another.

+
+
Parameters:
+
    +

  • from_path (Path) – The start point path.

    • +

  • to_path (Path) – The end point path.

    • +
+
+
Returns:
+

The relative path from ‘from_path’ (the start point) to ‘to_path’ (the end point).

+
+
Return type:
+

Path

+
+
Raises:
+

ValueError – If no relative path between ‘from_path’ and ‘to_path’ can be resolved.

+
+
+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/dictIO.utils.strings.html b/_autosummary/dictIO.utils.strings.html new file mode 100644 index 00000000..a1ba576f --- /dev/null +++ b/_autosummary/dictIO.utils.strings.html @@ -0,0 +1,583 @@ + + + + + + + + + dictIO.utils.strings - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

dictIO.utils.strings

+

Utility functions for string manipulation.

+

Functions

+
+ + + + + + + + + +

remove_quotes(string)

Remove quotes (single or double quotes) from the string object passed in.

string_diff(text_1, text_2)

Return diff line by line.

+
+
+
+dictIO.utils.strings.remove_quotes(string: str) → str
+

Remove quotes (single or double quotes) from the string object passed in.

+

Not only leading and trailing quotes are removed; also any quotes inside a string, if so, are removed.

+
+ +
+
+dictIO.utils.strings.string_diff(text_1: str, text_2: str) → str
+

Return diff line by line.

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.core.case.Case.html b/_autosummary/farn.core.case.Case.html new file mode 100644 index 00000000..91b77ad2 --- /dev/null +++ b/_autosummary/farn.core.case.Case.html @@ -0,0 +1,643 @@ + + + + + + + + + Case - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Case

+
+
+class farn.core.case.Case(case: str = '', layer: str = '', level: int = 0, no_of_samples: int = 0, index: int = 0, path: Path | None = None, *, is_leaf: bool = False, condition: MutableMapping[str, str] | None = None, parameters: MutableSequence[Parameter] | None = None, command_sets: MutableMapping[str, list[str]] | None = None)
+

Bases: object

+

Dataclass holding case attributes.

+
+
Case holds all relevant attributes needed by farn to process cases, e.g.
    +

  • condition

    • +

  • parameter names and associated values

    • +

  • commands

    • +
  • +
+
+
+
+
+__init__(case: str = '', layer: str = '', level: int = 0, no_of_samples: int = 0, index: int = 0, path: Path | None = None, *, is_leaf: bool = False, condition: MutableMapping[str, str] | None = None, parameters: MutableSequence[Parameter] | None = None, command_sets: MutableMapping[str, list[str]] | None = None) → None
+
+ +

Methods

+
+ + + + + + + + + + + + +

__init__([case, layer, level, ...])

add_parameters([parameters])

Manually add extra parameters.

to_dict()

Return a dict with all case attributes.

+
+

Attributes

+
+ + + + + + +

is_valid

Evaluates whether the case matches the configured filter expression.

+
+
+
+add_parameters(parameters: MutableSequence[Parameter] | MutableMapping[str, str] | None = None) → None
+

Manually add extra parameters.

+
+ +
+
+to_dict() → dict[str, Any]
+

Return a dict with all case attributes.

+
+
Returns:
+

dict with all case attributes

+
+
Return type:
+

Dict[str, Any]

+
+
+
+ +
+
+property is_valid: bool
+

Evaluates whether the case matches the configured filter expression.

+

A case is considered valid if it fulfils the filter citeria configured in farnDict for the respective layer.

+
+
Returns:
+

result of validity check. True indicates the case is valid, False not valid.

+
+
Return type:
+

bool

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.core.case.CaseStatus.html b/_autosummary/farn.core.case.CaseStatus.html new file mode 100644 index 00000000..d696ab9d --- /dev/null +++ b/_autosummary/farn.core.case.CaseStatus.html @@ -0,0 +1,666 @@ + + + + + + + + + CaseStatus - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

CaseStatus

+
+
+class farn.core.case.CaseStatus(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)
+

Bases: IntEnum

+

Enumeration class allowing an algorithm that processes cases, i.e. a simulator or case processor, +to indicate the state a case iscurrently in.

+
+
+__init__(*args, **kwds)
+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +

conjugate

Returns self, the complex conjugate of any int.

bit_length()

Number of bits necessary to represent self in binary.

bit_count()

Number of ones in the binary representation of the absolute value of self.

to_bytes([length, byteorder, signed])

Return an array of bytes representing an integer.

from_bytes([byteorder, signed])

Return the integer represented by the given array of bytes.

as_integer_ratio()

Return a pair of integers, whose ratio is equal to the original int.

is_integer()

Returns True.

__init__(*args, **kwds)

+
+

Attributes

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

real

the real part of a complex number

imag

the imaginary part of a complex number

numerator

the numerator of a rational number in lowest terms

denominator

the denominator of a rational number in lowest terms

NONE

FAILURE

PREPARED

RUNNING

SUCCESS

+
+
+
+FAILURE = 1
+
+ +
+
+NONE = 0
+
+ +
+
+PREPARED = 10
+
+ +
+
+RUNNING = 20
+
+ +
+
+SUCCESS = 30
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.core.case.Cases.html b/_autosummary/farn.core.case.Cases.html new file mode 100644 index 00000000..6542e79a --- /dev/null +++ b/_autosummary/farn.core.case.Cases.html @@ -0,0 +1,696 @@ + + + + + + + + + Cases - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Cases

+
+
+class farn.core.case.Cases(iterable=(), /)
+

Bases: list[Case]

+

Container Class for Cases.

+

Inherits from List[Case] and can hence be transparently used as a Python list type. +However, Cases extends its list base class by two convenience methods: +to_pandas() and to_numpy(), which turn the list of Case objects +into a pandas DataFrame or numpy ndarray, respectively.

+
+
+__init__(*args, **kwargs)
+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__(*args, **kwargs)

add_parameters([parameters])

Manually add extra parameters.

append(object, /)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable, /)

Extend list by appending elements from the iterable.

filter([levels, valid_only])

Return a sub-set of cases according to the passed in selection criteria.

index(value[, start, stop])

Return first index of value.

insert(index, object, /)

Insert object before index.

pop([index])

Remove and return item at index (default last).

remove(value, /)

Remove first occurrence of value.

reverse()

Reverse IN PLACE.

sort(*[, key, reverse])

Sort the list in ascending order and return None.

to_numpy()

Return parameter values of all cases as a 2-dimensional numpy array.

to_pandas(*[, use_path_as_index, ...])

Return cases as a pandas Dataframe.

+
+
+
+add_parameters(parameters: MutableSequence[Parameter] | MutableMapping[str, str] | None = None) → None
+

Manually add extra parameters.

+
+ +
+
+filter(levels: int | Sequence[int] = -1, *, valid_only: bool = True) → Cases
+

Return a sub-set of cases according to the passed in selection criteria.

+
+
Parameters:
+
    +

  • levels (Union[int, Sequence[int]], optional) – return all cases of a distinct level, or a sequence of levels. +level=-1 returns the last level (the leaf cases), by default -1

    • +

  • valid_only (bool, optional) – return only valid cases, i.e cases which pass a filter expression +defined for the case’s layer, by default True

    • +
+
+
Returns:
+

Cases object containing all cases that match the selection criteria.

+
+
Return type:
+

Cases

+
+
+
+ +
+
+to_numpy() → ndarray[tuple[int, int], dtype[float64]]
+

Return parameter values of all cases as a 2-dimensional numpy array.

+
+
Returns:
+

2-dimensional numpy array with case specific parameter values of all cases.

+
+
Return type:
+

ndarray[tuple[int, int], np.dtype[np.float64 | np.int32]]

+
+
+
+ +
+
+to_pandas(*, use_path_as_index: bool = True, parameters_only: bool = False) → DataFrame
+

Return cases as a pandas Dataframe.

+

Returns a DataFrame with case properties and case specific parameter values of all cases.

+
+
Parameters:
+
    +

  • use_path_as_index (bool, optional) – turn path column into index column, by default True

    • +

  • parameters_only (bool, optional) – reduce DataFrame to contain only the case’s parameter values, by default False

    • +
+
+
Returns:
+

DataFrame with case properties and case specific parameter values of all cases.

+
+
Return type:
+

DataFrame

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.core.case.html b/_autosummary/farn.core.case.html new file mode 100644 index 00000000..b39477e2 --- /dev/null +++ b/_autosummary/farn.core.case.html @@ -0,0 +1,552 @@ + + + + + + + + + farn.core.case - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.core.case

+

Classes

+
+ + + + + + + + + + + + +

Case([case, layer, level, no_of_samples, ...])

Dataclass holding case attributes.

CaseStatus(value[, names, module, qualname, ...])

Enumeration class allowing an algorithm that processes cases, i.e. a simulator or case processor, to indicate the state a case iscurrently in.

Cases([iterable])

Container Class for Cases.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.core.html b/_autosummary/farn.core.html new file mode 100644 index 00000000..83a46838 --- /dev/null +++ b/_autosummary/farn.core.html @@ -0,0 +1,549 @@ + + + + + + + + + farn.core - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+ +
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.core.parameter.Parameter.html b/_autosummary/farn.core.parameter.Parameter.html new file mode 100644 index 00000000..6f472b08 --- /dev/null +++ b/_autosummary/farn.core.parameter.Parameter.html @@ -0,0 +1,623 @@ + + + + + + + + + Parameter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Parameter

+
+
+class farn.core.parameter.Parameter(name: str = '', value: float | int | bool | str | None = None)
+

Bases: object

+

Dataclass holding the parameter attributes ‘name’ and ‘value’.

+
+
+__init__(name: str = '', value: float | int | bool | str | None = None) → None
+
+ +

Methods

+
+ + + + + + +

__init__([name, value])

+
+

Attributes

+
+ + + + + + + + + +

dtype

Returns the numpy dtype of the parameter.

type

Returns the Python type of the parameter.

+
+
+
+property dtype: dtype[float64] | dtype[int32] | dtype[bool_] | dtype[str_] | None
+

Returns the numpy dtype of the parameter.

+
+
Returns:
+

the numpy dtype, or None

+
+
Return type:
+

np.dtype[np.float64] | np.dtype[np.int32] | np.dtype[np.bool] | np.dtype[np.str] | None

+
+
+
+ +
+
+property type: type[float] | type[int] | type[bool] | type[str] | None
+

Returns the Python type of the parameter.

+
+
Returns:
+

the Python type

+
+
Return type:
+

Union[Type[float], Type[int], Type[bool], Type[str], None]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.core.parameter.html b/_autosummary/farn.core.parameter.html new file mode 100644 index 00000000..9d155007 --- /dev/null +++ b/_autosummary/farn.core.parameter.html @@ -0,0 +1,546 @@ + + + + + + + + + farn.core.parameter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.core.parameter

+

Classes

+
+ + + + + + +

Parameter([name, value])

Dataclass holding the parameter attributes 'name' and 'value'.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.farn.html b/_autosummary/farn.farn.html new file mode 100644 index 00000000..76114e2c --- /dev/null +++ b/_autosummary/farn.farn.html @@ -0,0 +1,760 @@ + + + + + + + + + farn.farn - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.farn

+

Functions

+
+ + + + + + + + + + + + + + + + + + + + + + + + +

create_case_folders(cases)

Create the case folder structure for the passed in cases.

create_case_list_files(cases[, target_dir, ...])

Create case list files for the specified nest levels.

create_cases(farn_dict, case_dir, *[, ...])

Create cases based on the layers, filter expressions and samples defined in the passed farn dict.

create_param_dict_files(cases)

Create the case specific paramDict files in the case folders of the passed in cases.

create_samples(farn_dict)

Run sampling and create the samples inside all layers of the passed in farn dict.

execute_command_set(cases, command_set, *[, ...])

Execute the given command set in the case folders of the passed in cases.

run_farn(farn_dict_file, *[, sample, ...])

Run farn.

+
+
+
+farn.farn.create_case_folders(cases: MutableSequence[Case]) → int
+

Create the case folder structure for the passed in cases.

+
+
Parameters:
+

cases (MutableSequence[Case]) – cases the case folders shall be created for.

+
+
Returns:
+

number of case folders created.

+
+
Return type:
+

int

+
+
+
+ +
+
+farn.farn.create_case_list_files(cases: MutableSequence[Case], target_dir: Path | None = None, levels: int | Sequence[int] | None = None) → list[Path]
+

Create case list files for the specified nest levels.

+

Case list files are simple text files containing a list of paths to all case folders +that share a common nest level within the case folder structure. +I.e. a case list file created for level 0 contains the paths to all case folders on level 0. +A case list file for level 1 contains the paths to all case folders on level 1, and so on.

+

These lists can be used i.e. in a batchProcess to execute shell commands +in all case folders of a specific nest level inside the case folder structure.

+
+
Parameters:
+
    +

  • cases (MutableSequence[Case]) – cases the case list files shall be created for

    • +

  • target_dir (Path, optional) – directory in which the case list files shall be created. +If None, current working directory will be used., by default None

    • +

  • levels (Union[int, Sequence[int], None], optional) – list of integers indicating the nest levels for which case list files shall be created. +If missing, by default a case list file for the deepest nest level (the leaf level) +will becreated., by default None

    • +
+
+
Returns:
+

The case list files that have been created (returned as a list of Path objects)

+
+
Return type:
+

list[Path]

+
+
+
+ +
+
+farn.farn.create_cases(farn_dict: MutableMapping[Any, Any], case_dir: Path, *, valid_only: bool = False) → Cases
+

Create cases based on the layers, filter expressions and samples defined in the passed farn dict.

+

Creates case objects for all cases derived by recursive permutation of layers +and the case specific samples defined per layer. +create_cases() creates one distinct case object for each case, +holding all case attributes (parameters) set to their case specific values.

+

Optionally, only _valid_ cases can be returned, i.e. cases which fulfill +the filter criteria configured for the respective layer. +Invalid cases then get excluded.

+

Note: +The corresponding case folder structure is not yet created by create_cases(). +Creating the case folder structure is the responsibility of create_case_folder_structure(). +However, the case_dir argument is passed in to allow create_cases() to already document in each case object +its _intended_ case folder path. This information is then read and used in create_case_folder_structure() +to actually create the case folders.

+
+
Parameters:
+
    +

  • farn_dict (MutableMapping) – farn dict. The farn dict must be sampled, +i.e. samples must have been generated for all layers defined in the farn dict.

    • +

  • case_dir (Path) – directory the case folder structure is (intended) to be generated in.

    • +

  • valid_only (bool) – whether or not only valid cases shall be returned, +i.e. cases which fulfill the filter criteria configured for the respective layer., by default False

    • +
+
+
Returns:
+

list of case objects representing all created cases.

+
+
Return type:
+

Cases

+
+
+
+ +
+
+farn.farn.create_param_dict_files(cases: MutableSequence[Case]) → int
+

Create the case specific paramDict files in the case folders of the passed in cases.

+

paramDict files contain the case specific parameters, meaning, via the paramDict files the case specific values +for all parameters get distributed to and persisted in the case folders.

+
+
Parameters:
+

cases (MutableSequence[Case]) – cases the paramDict file shall be created for

+
+
Returns:
+

number of paramDict files created

+
+
Return type:
+

int

+
+
+
+ +
+
+farn.farn.create_samples(farn_dict: SDict[str, Any]) → None
+

Run sampling and create the samples inside all layers of the passed in farn dict.

+

Creates the _samples element in each layer and populates it with the discrete samples +generated for the parameters defined and varied in the respective layer. +In case the _samples element already exists in a layer, it will be overwritten.

+
+
Parameters:
+

farn_dict (SDict[str, Any]) – farn dict the samples shall be created in

+
+
+
+ +
+
+farn.farn.execute_command_set(cases: MutableSequence[Case], command_set: str, *, batch: bool = True, test: bool = False) → int
+

Execute the given command set in the case folders of the passed in cases.

+
+
Parameters:
+
    +

  • cases (MutableSequence[Case]) – cases for which the specified command set shall be executed.

    • +

  • command_set (str) – name of the command set to be executed, as defined in farnDict

    • +

  • batch (bool, optional) – if True, executes the given command set in batch mode, i.e. asynchronously, by default False

    • +

  • test (bool, optional) – if True, executes command set in only first case folder where command set is defined, by default False

    • +
+
+
Returns:
+

number of case folders in which the command set has been executed

+
+
Return type:
+

int

+
+
+
+ +
+
+farn.farn.run_farn(farn_dict_file: str | PathLike[str], *, sample: bool = False, generate: bool = False, command: str | None = None, batch: bool = False, test: bool = False) → Cases
+

Run farn.

+

Runs the sampling for all layers as configured in farn dict, +generates the corresponding case folder structure and +executes user-defined shell command sets in all case folders.

+
+
Parameters:
+
    +

  • farn_dict_file (Union[str, os.PathLike[str]]) – farnDict file. Contains the farn configuration.

    • +

  • sample (bool, optional) – if True, runs the sampling defined for each layer and saves the sampled farnDict file with prefix sampled., +by default False

    • +

  • generate (bool, optional) – if True, generates the folder structure that spawns all layers and cases defined in farnDict, by default False

    • +

  • command (Union[str, None], optional) – executes the given command set in all case folders. +The command set must be defined in the commands section of the applicable layer in farnDict., +by default None

    • +

  • batch (bool, optional) – if True, executes the given command set in batch mode, i.e. asynchronously, by default False

    • +

  • test (bool, optional) – if True, runs only first case and returns, by default False

    • +
+
+
Returns:
+

List containing all valid leaf cases.

+
+
Return type:
+

Cases

+
+
Raises:
+

FileNotFoundError – if farn_dict_file does not exist

+
+
+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.batchProcess.AsyncBatchProcessor.html b/_autosummary/farn.run.batchProcess.AsyncBatchProcessor.html new file mode 100644 index 00000000..fe8bb503 --- /dev/null +++ b/_autosummary/farn.run.batchProcess.AsyncBatchProcessor.html @@ -0,0 +1,602 @@ + + + + + + + + + AsyncBatchProcessor - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

AsyncBatchProcessor

+
+
+class farn.run.batchProcess.AsyncBatchProcessor(case_list_file: Path, command: str, timeout: int = 3600, max_number_of_cpus: int = 0)
+

Bases: object

+

Batch processor for asynchroneous execution of a shell command in multiple case folders.

+
+
+__init__(case_list_file: Path, command: str, timeout: int = 3600, max_number_of_cpus: int = 0) → None
+

Instantiate an asynchroneous batch processor +to execute a shell command in multiple case folders.

+
+
Parameters:
+
    +

  • case_list_file (Path) – the file containing the list of case folders the shell command shall be executed in

    • +

  • command (str) – the shell command to be executed

    • +

  • timeout (int, optional) – time out in seconds, by default 3600

    • +

  • max_number_of_cpus (int, optional) – number of cpus to be used, by default 0

    • +
+
+
+
+ +

Methods

+
+ + + + + + + + + +

__init__(case_list_file, command[, timeout, ...])

Instantiate an asynchroneous batch processor to execute a shell command in multiple case folders.

run()

Run the shell command in all case folders.

+
+
+
+run() → None
+

Run the shell command in all case folders.

+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.batchProcess.html b/_autosummary/farn.run.batchProcess.html new file mode 100644 index 00000000..9598565f --- /dev/null +++ b/_autosummary/farn.run.batchProcess.html @@ -0,0 +1,546 @@ + + + + + + + + + farn.run.batchProcess - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.run.batchProcess

+

Classes

+
+ + + + + + +

AsyncBatchProcessor(case_list_file, command)

Batch processor for asynchroneous execution of a shell command in multiple case folders.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.cli.batchProcess.html b/_autosummary/farn.run.cli.batchProcess.html new file mode 100644 index 00000000..65526fb5 --- /dev/null +++ b/_autosummary/farn.run.cli.batchProcess.html @@ -0,0 +1,572 @@ + + + + + + + + + farn.run.cli.batchProcess - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.run.cli.batchProcess

+

Functions

+
+ + + + + + +

main()

Entry point for console script as configured in setup.cfg.

+
+
+
+farn.run.cli.batchProcess.main() → None
+

Entry point for console script as configured in setup.cfg.

+

Runs the command line interface and parses arguments and options entered on the console.

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.cli.html b/_autosummary/farn.run.cli.html new file mode 100644 index 00000000..1a66a6a5 --- /dev/null +++ b/_autosummary/farn.run.cli.html @@ -0,0 +1,546 @@ + + + + + + + + + farn.run.cli - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+ +
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.html b/_autosummary/farn.run.html new file mode 100644 index 00000000..181774af --- /dev/null +++ b/_autosummary/farn.run.html @@ -0,0 +1,555 @@ + + + + + + + + + farn.run - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+ +
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.subProcess.html b/_autosummary/farn.run.subProcess.html new file mode 100644 index 00000000..52581805 --- /dev/null +++ b/_autosummary/farn.run.subProcess.html @@ -0,0 +1,574 @@ + + + + + + + + + farn.run.subProcess - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.run.subProcess

+

Functions

+
+ + + + + + +

execute_in_sub_process(command[, path, timeout])

Create a subprocess with cwd = path and executes the given shell command.

+
+
+
+farn.run.subProcess.execute_in_sub_process(command: str, path: Path | None = None, timeout: int | None = 7200) → tuple[bytes, bytes]
+

Create a subprocess with cwd = path and executes the given shell command. +The subprocess runs asyncroneous. The calling thread waits until the subprocess returns +or until timeout is exceeded. +If the subprocess has not returned after [timeout] seconds, the subprocess gets killed.

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.utils.html b/_autosummary/farn.run.utils.html new file mode 100644 index 00000000..cc8f99f3 --- /dev/null +++ b/_autosummary/farn.run.utils.html @@ -0,0 +1,546 @@ + + + + + + + + + farn.run.utils - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.run.utils

+

Modules

+
+ + + + + + +

threading

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.utils.threading.JobQueue.html b/_autosummary/farn.run.utils.threading.JobQueue.html new file mode 100644 index 00000000..810799f4 --- /dev/null +++ b/_autosummary/farn.run.utils.threading.JobQueue.html @@ -0,0 +1,627 @@ + + + + + + + + + JobQueue - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

JobQueue

+
+
+class farn.run.utils.threading.JobQueue(maxsize=0)
+

Bases: Queue[tuple[Any, Sequence[Any], Mapping[str, Any]]]

+

Queue for jobs to be executed by worker threads.

+

JobQueue extends threading.Queue. +It provides an additional put_callable() method, allowing to put +a callable with a generic list of arguments in the queue.

+
+
+__init__(maxsize=0)
+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__([maxsize])

empty()

Return True if the queue is empty, False otherwise (not reliable!).

full()

Return True if the queue is full, False otherwise (not reliable!).

get([block, timeout])

Remove and return an item from the queue.

get_nowait()

Remove and return an item from the queue without blocking.

join()

Blocks until all items in the Queue have been gotten and processed.

put(item[, block, timeout])

Put an item into the queue.

put_callable(func, *args, **kwargs)

Put a callable object (function) in the JobQueue.

put_nowait(item)

Put an item into the queue without blocking.

qsize()

Return the approximate size of the queue (not reliable!).

task_done()

Indicate that a formerly enqueued task is complete.

+
+
+
+put_callable(func: Callable[[...], Any], *args: Any, **kwargs: Any) → None
+

Put a callable object (function) in the JobQueue.

+

Additional positional and keyword arguments provided with args and kwargs +will be passed on to the called function.

+
+
Parameters:
+

func (Any) – the callable object (function)

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.utils.threading.Worker.html b/_autosummary/farn.run.utils.threading.Worker.html new file mode 100644 index 00000000..afb2a9e5 --- /dev/null +++ b/_autosummary/farn.run.utils.threading.Worker.html @@ -0,0 +1,636 @@ + + + + + + + + + Worker - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Worker

+
+
+class farn.run.utils.threading.Worker(job_queue: JobQueue)
+

Bases: Thread

+

Worker thread executing jobs from a job queue.

+
+
+__init__(job_queue: JobQueue) → None
+

Instantiate a Worker and bind it to the passed in JobQueue instance.

+
+
Parameters:
+

job_queue (JobQueue) – the JobQueue this Worker shall be bound to

+
+
+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

__init__(job_queue)

Instantiate a Worker and bind it to the passed in JobQueue instance.

getName()

Return a string used for identification purposes only.

isDaemon()

Return whether this thread is a daemon.

is_alive()

Return whether the thread is alive.

join([timeout])

Wait until the thread terminates.

run()

Run the next job from the JobQueue this Worker is bound to.

setDaemon(daemonic)

Set whether this thread is a daemon.

setName(name)

Set the name string for this thread.

start()

Start the thread's activity.

+
+

Attributes

+
+ + + + + + + + + + + + + + + +

daemon

A boolean value indicating whether this thread is a daemon thread.

ident

Thread identifier of this thread or None if it has not been started.

name

A string used for identification purposes only.

native_id

Native integral thread ID of this thread, or None if it has not been started.

+
+
+
+run() → None
+

Run the next job from the JobQueue this Worker is bound to.

+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.run.utils.threading.html b/_autosummary/farn.run.utils.threading.html new file mode 100644 index 00000000..a7fd2bf3 --- /dev/null +++ b/_autosummary/farn.run.utils.threading.html @@ -0,0 +1,549 @@ + + + + + + + + + farn.run.utils.threading - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.run.utils.threading

+

Classes

+
+ + + + + + + + + +

JobQueue([maxsize])

Queue for jobs to be executed by worker threads.

Worker(job_queue)

Worker thread executing jobs from a job queue.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.sampling.html b/_autosummary/farn.sampling.html new file mode 100644 index 00000000..ceaeef3e --- /dev/null +++ b/_autosummary/farn.sampling.html @@ -0,0 +1,546 @@ + + + + + + + + + farn.sampling - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.sampling

+

Modules

+
+ + + + + + +

sampling

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.sampling.sampling.DiscreteSampling.html b/_autosummary/farn.sampling.sampling.DiscreteSampling.html new file mode 100644 index 00000000..f718bc70 --- /dev/null +++ b/_autosummary/farn.sampling.sampling.DiscreteSampling.html @@ -0,0 +1,639 @@ + + + + + + + + + DiscreteSampling - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

DiscreteSampling

+
+
+class farn.sampling.sampling.DiscreteSampling(seed: int | None = None)
+

Bases: object

+

Class providing methods to run a discrete sampling of a specific layer, +i.e. of all variables defined in the given layer.

+
+
+__init__(seed: int | None = None) → None
+
+ +

Methods

+
+ + + + + + + + + + + + + + + +

__init__([seed])

generate_samples()

Return a dict with all generated samples for the layer this sampling is run on.

set_sampling_parameters(sampling_parameters)

Set the sampling parameters.

set_sampling_type(sampling_type)

Set the sampling type.

+
+
+
+generate_samples() → dict[str, list[Any]]
+

Return a dict with all generated samples for the layer this sampling is run on.

+

The first element in the returned dict contains the case names generated. +All following elements (second to last) contain the values sampled +for each variable defined in the layer this sampling is run on. +I.e. +“names”: (case_name_1, case_name_2, .., case_name_n) +“variable_1”: (value_1, value_2, .., value_n) +… +“variable_m”: (value_1, value_2, .., value_n)

+
+
Returns:
+

the dict with all generated samples

+
+
Return type:
+

Dict[str, List[Any]]

+
+
+
+ +
+
+set_sampling_parameters(sampling_parameters: Mapping[str, Any], layer_name: str = '') → None
+

Set the sampling parameters.

+

The passed-in sampling parameters will be validated. +Upon successful validation, the sampling is configured using the provided parameters.

+
+ +
+
+set_sampling_type(sampling_type: str) → None
+

Set the sampling type.

+
+
Valid values:

“fixed” +“linSpace” +“uniformLhs” +“normalLhs” +“sobol” +“arbitrary” +“hilbertCurve”

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.sampling.sampling.html b/_autosummary/farn.sampling.sampling.html new file mode 100644 index 00000000..a25b822b --- /dev/null +++ b/_autosummary/farn.sampling.sampling.html @@ -0,0 +1,546 @@ + + + + + + + + + farn.sampling.sampling - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.sampling.sampling

+

Classes

+
+ + + + + + +

DiscreteSampling([seed])

Class providing methods to run a discrete sampling of a specific layer, i.e. of all variables defined in the given layer.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.utils.html b/_autosummary/farn.utils.html new file mode 100644 index 00000000..a9de93bf --- /dev/null +++ b/_autosummary/farn.utils.html @@ -0,0 +1,549 @@ + + + + + + + + + farn.utils - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.utils

+

Modules

+
+ + + + + + + + + +

logging

Functions to configure logging for the application.

os

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.utils.logging.html b/_autosummary/farn.utils.logging.html new file mode 100644 index 00000000..cbfb6d87 --- /dev/null +++ b/_autosummary/farn.utils.logging.html @@ -0,0 +1,590 @@ + + + + + + + + + farn.utils.logging - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.utils.logging

+

Functions to configure logging for the application.

+

Functions

+
+ + + + + + + + + +

configure_logging([log_level_console, ...])

Configure logging for the application, allowing for both console and file logging.

plural(count[, string])

Conditionally returns the singular or plural form of the passed in string.

+
+
+
+farn.utils.logging.configure_logging(log_level_console: str = 'WARNING', log_file: Path | None = None, log_level_file: str = 'WARNING') → None
+

Configure logging for the application, allowing for both console and file logging.

+

Sets the log levels and formats for the output, ensuring that logs are captured as specified.

+
+
Parameters:
+
    +

  • log_level_console (str, optional) – log level for console output, by default “WARNING”

    • +

  • log_file (Path | None, optional) – log file to be used. If None, file logging is disabled. by default None

    • +

  • log_level_file (str, optional) – log level for file output, by default “WARNING”

    • +
+
+
Raises:
+

TypeError – if an invalid value for log_level_console or log_level_file is passed

+
+
+

Examples

+

configure_logging(log_level_console=”INFO”, log_file=Path(“app.log”), log_level_file=”DEBUG”)

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/farn.utils.os.html b/_autosummary/farn.utils.os.html new file mode 100644 index 00000000..250c47ab --- /dev/null +++ b/_autosummary/farn.utils.os.html @@ -0,0 +1,571 @@ + + + + + + + + + farn.utils.os - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

farn.utils.os

+

Functions

+
+ + + + + + +

append_system_variable(variable, value)

Append system variable depending on system.

+
+
+
+farn.utils.os.append_system_variable(variable: str, value: str) → None
+

Append system variable depending on system.

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.component.Component.html b/_autosummary/ospx.component.Component.html new file mode 100644 index 00000000..fdfaf1a3 --- /dev/null +++ b/_autosummary/ospx.component.Component.html @@ -0,0 +1,684 @@ + + + + + + + + + Component - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Component

+
+
+class ospx.component.Component(name: str, properties: MutableMapping[Any, Any])
+

Bases: object

+

A component is an instance of a (component-) model.

+

A component represents an instance of a (component-) model. +Any system structure can contain an arbitrary number of components. +Important here is, that multiple components in a system structure can be instances of one and the same model. +In practical terms this means that multiple components can refer to the same physical FMU file. n +As components are instances of a model (FMU), they inherit the start values defined +in the FMU’s modelDescription file upon instantiation; n +howevere, being an instance, each component can alter and overwrite these start values. +This is accomplished using the ‘initialize’ section inside a ‘component’ element in the ospx case dict. n +See https://dnv-opensource.github.io/ospx/fileFormat.caseDict.html

+

Equivalent terms to ‘component’ are: n +t ‘Simulator’ in OSP. See https://open-simulation-platform.github.io/libcosim/configuration#simulator n +t ‘Simulation model’ in FMI for co-simulation. See https://github.com/modelica/fmi-standard/releases/download/v2.0.3/FMI-Specification-2.0.3.pdf n +t ‘Component’ in SSP. See https://ssp-standard.org/publications/SSP10/SystemStructureAndParameterization10.pdf

+
+
+__init__(name: str, properties: MutableMapping[Any, Any]) → None
+
+ +

Methods

+
+ + + + + + + + + +

__init__(name, properties)

write_osp_model_description_xml()

Write the <component.name>_OspModelDescription.xml file in the current working directory.

+
+

Attributes

+
+ + + + + + + + + + + + + + + +

connectors

Returns a dict with all connectors defined by the component.

units

Returns a dict with all units defined in the component.

variables

Returns a dict with all scalar variables defined in the component.

variables_with_start_values

Return all scalar variables with start values.

+
+
+
+write_osp_model_description_xml() → None
+

Write the <component.name>_OspModelDescription.xml file in the current working directory.

+
+ +
+
+property connectors: dict[str, Connector]
+

Returns a dict with all connectors defined by the component.

+
+
Returns:
+

dict with all connectors

+
+
Return type:
+

dict[str, Connector]

+
+
+
+ +
+
+property units: dict[str, Unit]
+

Returns a dict with all units defined in the component.

+
+
Returns:
+

dict with all units

+
+
Return type:
+

dict[str, Unit]

+
+
+
+ +
+
+property variables: dict[str, ScalarVariable]
+

Returns a dict with all scalar variables defined in the component.

+
+
Returns:
+

dict with all scalar variables

+
+
Return type:
+

dict[str, ScalarVariable]

+
+
+
+ +
+
+property variables_with_start_values: dict[str, ScalarVariable]
+

Return all scalar variables with start values.

+

Returns a dict with all scalar variables for which start values (initial values) +are defined in the component.

+
+
Returns:
+

dict with all scalar variables with start values defined.

+
+
Return type:
+

dict[str, ScalarVariable]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.component.RemoteAccess.html b/_autosummary/ospx.component.RemoteAccess.html new file mode 100644 index 00000000..fffc9661 --- /dev/null +++ b/_autosummary/ospx.component.RemoteAccess.html @@ -0,0 +1,605 @@ + + + + + + + + + RemoteAccess - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

RemoteAccess

+
+
+class ospx.component.RemoteAccess(host: str = <factory>, port: int = 0)
+

Bases: object

+

Data class holding the host and port information for a remote connection.

+
+
+__init__(host: str = <factory>, port: int = 0) → None
+
+ +

Methods

+
+ + + + + + +

__init__([host, port])

+
+

Attributes

+
+ + + + + + + + + +

port

host

+
+
+
+host: str
+
+ +
+
+port: int = 0
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.component.html b/_autosummary/ospx.component.html new file mode 100644 index 00000000..790d58cb --- /dev/null +++ b/_autosummary/ospx.component.html @@ -0,0 +1,549 @@ + + + + + + + + + ospx.component - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.component

+

Classes

+
+ + + + + + + + + +

Component(name, properties)

A component is an instance of a (component-) model.

RemoteAccess(host, port)

Data class holding the host and port information for a remote connection.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.connection.Connection.html b/_autosummary/ospx.connection.Connection.html new file mode 100644 index 00000000..54cb6634 --- /dev/null +++ b/_autosummary/ospx.connection.Connection.html @@ -0,0 +1,642 @@ + + + + + + + + + Connection - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Connection

+
+
+class ospx.connection.Connection(name: str, source_endpoint: Endpoint, target_endpoint: Endpoint)
+

Bases: object

+

A connection is the primary artefact to connect outputs and inputs of componoents in a system.

+

A connection connects an output connector of one component with an input connector of another component.

+
+
+__init__(name: str, source_endpoint: Endpoint, target_endpoint: Endpoint) → None
+
+ +

Methods

+
+ + + + + + +

__init__(name, source_endpoint, target_endpoint)

+
+

Attributes

+
+ + + + + + + + + + + + +

is_valid

Consistency check.

is_variable_connection

Returns True if connection is a single variable connection.

is_variable_group_connection

Returns True if connection is a variable group connection.

+
+
+
+property is_valid: bool
+

Consistency check. Returns True if connection is found fully defined and valid.

+
+
Returns:
+

True if valid. Otherwise False.

+
+
Return type:
+

bool

+
+
+
+ +
+
+property is_variable_connection: bool
+

Returns True if connection is a single variable connection.

+
+
Returns:
+

True if single variable connection. Otherwise False.

+
+
Return type:
+

bool

+
+
+
+ +
+
+property is_variable_group_connection: bool
+

Returns True if connection is a variable group connection.

+
+
Returns:
+

True if variable group connection. Otherwise False.

+
+
Return type:
+

bool

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.connection.Endpoint.html b/_autosummary/ospx.connection.Endpoint.html new file mode 100644 index 00000000..0d3e2cd8 --- /dev/null +++ b/_autosummary/ospx.connection.Endpoint.html @@ -0,0 +1,662 @@ + + + + + + + + + Endpoint - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Endpoint

+
+
+class ospx.connection.Endpoint(component: Component, connector: Connector | None = None, variable: ScalarVariable | None = None)
+

Bases: object

+

Endpoints relate each side of a connection to distinct variables or connectors.

+

An endpoint is for a connection what a connector is for a component. +A connection has two endpoints, one for each side. +Connection endpoints are hence the ‘counterparts’ to component’s connectors.

+
+
+__init__(component: Component, connector: Connector | None = None, variable: ScalarVariable | None = None) → None
+
+ +

Methods

+
+ + + + + + +

__init__(component[, connector, variable])

+
+

Attributes

+
+ + + + + + + + + + + + + + + +

connector

Returns the connector this endpoint refers to, if defined.

is_valid

Consistency check.

variable

Returns the scalar variable this endpoint refers to, if defined.

variable_name

Returns the name of the scalar variable this endpoint refers to.

+
+
+
+property connector: Connector | None
+

Returns the connector this endpoint refers to, if defined.

+
+
Returns:
+

the connector, if defined. Otherwise None.

+
+
Return type:
+

Union[Connector, None]

+
+
+
+ +
+
+property is_valid: bool
+

Consistency check. Returns True if endpoint is defined and valid.

+
+
Returns:
+

True if valid. Otherwise False.

+
+
Return type:
+

bool

+
+
+
+ +
+
+property variable: ScalarVariable | None
+

Returns the scalar variable this endpoint refers to, if defined.

+
+
Returns:
+

the scalar variable, if defined. Otherwise None.

+
+
Return type:
+

Union[ScalarVariable, None]

+
+
+
+ +
+
+property variable_name: str
+

Returns the name of the scalar variable this endpoint refers to.

+
+
Returns:
+

the name of the scalar variable.

+
+
Return type:
+

str

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.connection.html b/_autosummary/ospx.connection.html new file mode 100644 index 00000000..038fbd72 --- /dev/null +++ b/_autosummary/ospx.connection.html @@ -0,0 +1,549 @@ + + + + + + + + + ospx.connection - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.connection

+

Classes

+
+ + + + + + + + + +

Connection(name, source_endpoint, ...)

A connection is the primary artefact to connect outputs and inputs of componoents in a system.

Endpoint(component[, connector, variable])

Endpoints relate each side of a connection to distinct variables or connectors.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.connector.Connector.html b/_autosummary/ospx.connector.Connector.html new file mode 100644 index 00000000..a68f493f --- /dev/null +++ b/_autosummary/ospx.connector.Connector.html @@ -0,0 +1,691 @@ + + + + + + + + + Connector - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Connector

+
+
+class ospx.connector.Connector(name: str, variable: str | None = None, variable_group: str | None = None, type: str | None = None)
+

Bases: object

+

Class representing a connector.

+

Connectors allow to explicitely make public a components scalar variable or variable group +at the component’s outer interface.

+

An connector is for a component what an endpoint is for a connection. +Connectors are hence the ‘counterparts’ to connection’s endpoints.

+
+
+__init__(name: str, variable: str | None = None, variable_group: str | None = None, type: str | None = None) → None
+
+ +

Methods

+
+ + + + + + +

__init__(name[, variable, variable_group, type])

+
+

Attributes

+
+ + + + + + + + + + + + + + + + + + + + + +

is_group_connector

Returns True if connector is a variable group connector.

is_single_connector

Returns True if connector is a single variable connector.

type

Returns the type of the connector.

variable

Returns the scalar variable this connector is defined for.

variable_group

Returns the variable group this connector is defined for.

variable_name

Returns the name of the variable or variable group this connector is defined for.

+
+
+
+property is_group_connector: bool
+

Returns True if connector is a variable group connector.

+
+
Returns:
+

True if variable group connector. Otherwise False.

+
+
Return type:
+

bool

+
+
+
+ +
+
+property is_single_connector: bool
+

Returns True if connector is a single variable connector.

+
+
Returns:
+

True if single variable connector. Otherwise False.

+
+
Return type:
+

bool

+
+
+
+ +
+
+property type: str | None
+

Returns the type of the connector.

+
+ +
+
+property variable: str | None
+

Returns the scalar variable this connector is defined for.

+
+
Returns:
+

the scalar variable, if connector is a group connector. Otherwise None.

+
+
Return type:
+

Union[str, None]

+
+
+
+ +
+
+property variable_group: str | None
+

Returns the variable group this connector is defined for.

+
+
Returns:
+

the variable group, if connector is a group connector. Otherwise None.

+
+
Return type:
+

Union[str, None]

+
+
+
+ +
+
+property variable_name: str
+

Returns the name of the variable or variable group this connector is defined for.

+
+
Returns:
+

name of the variable or variable group

+
+
Return type:
+

str

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.connector.html b/_autosummary/ospx.connector.html new file mode 100644 index 00000000..7b66673f --- /dev/null +++ b/_autosummary/ospx.connector.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.connector - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.connector

+

Classes

+
+ + + + + + +

Connector(name[, variable, variable_group, type])

Class representing a connector.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.experiment.Experiment.html b/_autosummary/ospx.fmi.experiment.Experiment.html new file mode 100644 index 00000000..4d74d4d1 --- /dev/null +++ b/_autosummary/ospx.fmi.experiment.Experiment.html @@ -0,0 +1,624 @@ + + + + + + + + + Experiment - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Experiment

+
+
+class ospx.fmi.experiment.Experiment(start_time: float | None = None, stop_time: float | None = None, tolerance: float | None = None, step_size: float | None = None)
+

Bases: object

+

Data class for the DefaultExperiment element inside fmi 2.0 ModelDescription.

+

See https://github.com/modelica/fmi-standard/blob/v2.0.x/schema/fmi2ModelDescription.xsd

+
+
+__init__(start_time: float | None = None, stop_time: float | None = None, tolerance: float | None = None, step_size: float | None = None) → None
+
+ +

Methods

+
+ + + + + + +

__init__([start_time, stop_time, tolerance, ...])

+
+

Attributes

+
+ + + + + + + + + + + + + + + +

start_time

step_size

stop_time

tolerance

+
+
+
+start_time: float | None = None
+
+ +
+
+step_size: float | None = None
+
+ +
+
+stop_time: float | None = None
+
+ +
+
+tolerance: float | None = None
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.experiment.html b/_autosummary/ospx.fmi.experiment.html new file mode 100644 index 00000000..e5926a40 --- /dev/null +++ b/_autosummary/ospx.fmi.experiment.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.fmi.experiment - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.fmi.experiment

+

Classes

+
+ + + + + + +

Experiment([start_time, stop_time, ...])

Data class for the DefaultExperiment element inside fmi 2.0 ModelDescription.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.fmu.FMU.html b/_autosummary/ospx.fmi.fmu.FMU.html new file mode 100644 index 00000000..d95e1778 --- /dev/null +++ b/_autosummary/ospx.fmi.fmu.FMU.html @@ -0,0 +1,688 @@ + + + + + + + + + FMU - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

FMU

+
+
+class ospx.fmi.fmu.FMU(file: str | PathLike[str])
+

Bases: object

+

Class to read and interact with an fmi 2.0 Functional Mockup Unit (FMU).

+

See also https://github.com/modelica/fmi-standard/blob/v2.0.x/schema/fmi2ModelDescription.xsd

+
+
+__init__(file: str | PathLike[str]) → None
+
+ +

Methods

+
+ + + + + + + + + + + + +

__init__(file)

copy(new_name)

Save a copy of the FMU with a new name.

proxify(host, port)

Create a proxy version of the FMU.

+
+

Attributes

+
+ + + + + + + + + + + + +

default_experiment

Returns the default experiment, if defined in the FMU.

units

Returns a dict with all units defined in the FMU.

variables

Returns a dict with all scalar variables defined in the FMU.

+
+
+
+copy(new_name: str) → FMU
+

Save a copy of the FMU with a new name.

+
+
Parameters:
+

new_name (str) – Intended name of the copy. The new name must be different from the existing name.

+
+
Returns:
+

The new FMU

+
+
Return type:
+

FMU

+
+
+
+ +
+
+proxify(host: str, port: int) → FMU
+

Create a proxy version of the FMU.

+

For details see https://github.com/NTNU-IHB/FMU-proxy

+
+
Parameters:
+
    +

  • host (str) – Remote host

    • +

  • port (int) – Remote port

    • +
+
+
Returns:
+

The created proxy version of the FMU

+
+
Return type:
+

FMU

+
+
+
+ +
+
+property default_experiment: Experiment | None
+

Returns the default experiment, if defined in the FMU.

+
+
Returns:
+

the default experiment, if defined. Otherwise None.

+
+
Return type:
+

Union[Experiment, None]

+
+
+
+ +
+
+property units: dict[str, Unit]
+

Returns a dict with all units defined in the FMU.

+
+
Returns:
+

dict with all units

+
+
Return type:
+

Dict[str, Unit]

+
+
+
+ +
+
+property variables: dict[str, ScalarVariable]
+

Returns a dict with all scalar variables defined in the FMU.

+
+
Returns:
+

dict with all scalar variables

+
+
Return type:
+

dict[str, ScalarVariable]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.fmu.html b/_autosummary/ospx.fmi.fmu.html new file mode 100644 index 00000000..cdb86ede --- /dev/null +++ b/_autosummary/ospx.fmi.fmu.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.fmi.fmu - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.fmi.fmu

+

Classes

+
+ + + + + + +

FMU(file)

Class to read and interact with an fmi 2.0 Functional Mockup Unit (FMU).

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.html b/_autosummary/ospx.fmi.html new file mode 100644 index 00000000..84c61360 --- /dev/null +++ b/_autosummary/ospx.fmi.html @@ -0,0 +1,555 @@ + + + + + + + + + ospx.fmi - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+ +
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.unit.BaseUnit.html b/_autosummary/ospx.fmi.unit.BaseUnit.html new file mode 100644 index 00000000..4ff5d139 --- /dev/null +++ b/_autosummary/ospx.fmi.unit.BaseUnit.html @@ -0,0 +1,680 @@ + + + + + + + + + BaseUnit - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

BaseUnit

+
+
+class ospx.fmi.unit.BaseUnit(kg: int = 0, m: int = 0, s: int = 0, A: int = 0, K: int = 0, mol: int = 0, cd: int = 0, rad: int = 0, factor: float = 1.0, offset: float = 0.0)
+

Bases: object

+

fmi 2.0 BaseUnit.

+

Unit definition with reference to SI base units n +base unit value = factor * unit value + offset n +See https://github.com/modelica/fmi-standard/blob/v2.0.x/schema/fmi2Unit.xsd

+
+
+__init__(kg: int = 0, m: int = 0, s: int = 0, A: int = 0, K: int = 0, mol: int = 0, cd: int = 0, rad: int = 0, factor: float = 1.0, offset: float = 0.0) → None
+
+ +

Methods

+
+ + + + + + +

__init__([kg, m, s, A, K, mol, cd, rad, ...])

+
+

Attributes

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

A

K

cd

factor

kg

m

mol

offset

rad

s

+
+
+
+A: int = 0
+
+ +
+
+K: int = 0
+
+ +
+
+cd: int = 0
+
+ +
+
+factor: float = 1.0
+
+ +
+
+kg: int = 0
+
+ +
+
+m: int = 0
+
+ +
+
+mol: int = 0
+
+ +
+
+offset: float = 0.0
+
+ +
+
+rad: int = 0
+
+ +
+
+s: int = 0
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.unit.DisplayUnit.html b/_autosummary/ospx.fmi.unit.DisplayUnit.html new file mode 100644 index 00000000..cd9118b7 --- /dev/null +++ b/_autosummary/ospx.fmi.unit.DisplayUnit.html @@ -0,0 +1,616 @@ + + + + + + + + + DisplayUnit - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

DisplayUnit

+
+
+class ospx.fmi.unit.DisplayUnit(name: str = <factory>, factor: float = 1.0, offset: float = 0.0)
+

Bases: object

+

fmi 2.0 DisplayUnit.

+

display unit value = factor * unit value + offset n +See https://github.com/modelica/fmi-standard/blob/v2.0.x/schema/fmi2Unit.xsd

+
+
+__init__(name: str = <factory>, factor: float = 1.0, offset: float = 0.0) → None
+
+ +

Methods

+
+ + + + + + +

__init__([name, factor, offset])

+
+

Attributes

+
+ + + + + + + + + + + + +

factor

offset

name

+
+
+
+factor: float = 1.0
+
+ +
+
+name: str
+
+ +
+
+offset: float = 0.0
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.unit.Unit.html b/_autosummary/ospx.fmi.unit.Unit.html new file mode 100644 index 00000000..4c3702ca --- /dev/null +++ b/_autosummary/ospx.fmi.unit.Unit.html @@ -0,0 +1,615 @@ + + + + + + + + + Unit - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Unit

+
+
+class ospx.fmi.unit.Unit(name: str = <factory>, base_unit: ~ospx.fmi.unit.BaseUnit | None = None, display_unit: ~ospx.fmi.unit.DisplayUnit = <factory>)
+

Bases: object

+

fmi 2.0 Unit Definition.

+

See https://github.com/modelica/fmi-standard/blob/v2.0.x/schema/fmi2Unit.xsd

+
+
+__init__(name: str = <factory>, base_unit: ~ospx.fmi.unit.BaseUnit | None = None, display_unit: ~ospx.fmi.unit.DisplayUnit = <factory>) → None
+
+ +

Methods

+
+ + + + + + +

__init__([name, base_unit, display_unit])

+
+

Attributes

+
+ + + + + + + + + + + + +

base_unit

name

display_unit

+
+
+
+base_unit: BaseUnit | None = None
+
+ +
+
+display_unit: DisplayUnit
+
+ +
+
+name: str
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.unit.html b/_autosummary/ospx.fmi.unit.html new file mode 100644 index 00000000..1550a475 --- /dev/null +++ b/_autosummary/ospx.fmi.unit.html @@ -0,0 +1,552 @@ + + + + + + + + + ospx.fmi.unit - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.fmi.unit

+

Classes

+
+ + + + + + + + + + + + +

BaseUnit([kg, m, s, A, K, mol, cd, rad, ...])

fmi 2.0 BaseUnit.

DisplayUnit(name, factor, offset)

fmi 2.0 DisplayUnit.

Unit(name, base_unit, display_unit)

fmi 2.0 Unit Definition.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.variable.ScalarVariable.html b/_autosummary/ospx.fmi.variable.ScalarVariable.html new file mode 100644 index 00000000..532cac28 --- /dev/null +++ b/_autosummary/ospx.fmi.variable.ScalarVariable.html @@ -0,0 +1,628 @@ + + + + + + + + + ScalarVariable - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ScalarVariable

+
+
+class ospx.fmi.variable.ScalarVariable(name: str, data_type: str | None = None, causality: str | None = None, variability: str | None = None, start: int | float | bool | str | None = None, value_reference: int = 0, description: str | None = None, quantity: str | None = None, unit: str | None = None, display_unit: str | None = None)
+

Bases: object

+

fmi 2.0 ScalarVariable.

+

See https://github.com/modelica/fmi-standard/blob/v2.0.x/schema/fmi2ScalarVariable.xsd

+
+
+__init__(name: str, data_type: str | None = None, causality: str | None = None, variability: str | None = None, start: int | float | bool | str | None = None, value_reference: int = 0, description: str | None = None, quantity: str | None = None, unit: str | None = None, display_unit: str | None = None) → None
+
+ +

Methods

+
+ + + + + + +

__init__(name[, data_type, causality, ...])

+
+

Attributes

+
+ + + + + + + + + + + + + + + +

causality

Returns the causality of the scalar Variable.

data_type

Returns the FMI data type of the scalar Variable.

start

Returns the start value (initial value) of the scalar Variable.

variability

Returns the variability of the scalar Variable.

+
+
+
+property causality: str
+

Returns the causality of the scalar Variable.

+
+ +
+
+property data_type: str | None
+

Returns the FMI data type of the scalar Variable.

+
+ +
+
+property start: int | float | bool | str | None
+

Returns the start value (initial value) of the scalar Variable.

+
+ +
+
+property variability: str | None
+

Returns the variability of the scalar Variable.

+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.fmi.variable.html b/_autosummary/ospx.fmi.variable.html new file mode 100644 index 00000000..a20c5cc4 --- /dev/null +++ b/_autosummary/ospx.fmi.variable.html @@ -0,0 +1,594 @@ + + + + + + + + + ospx.fmi.variable - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.fmi.variable

+

Functions

+
+ + + + + + +

get_fmi_data_type(arg)

Return the fmi 2.0 data type corresponding to Python type of the passed in argument.

+
+

Classes

+
+ + + + + + +

ScalarVariable(name[, data_type, causality, ...])

fmi 2.0 ScalarVariable.

+
+
+
+ospx.fmi.variable.get_fmi_data_type(arg: object) → str
+

Return the fmi 2.0 data type corresponding to Python type of the passed in argument.

+

See https://github.com/modelica/fmi-standard/blob/v2.0.x/schema/fmi2Type.xsd

+
+
Parameters:
+

arg (Any) – The argument for which the fmi 2.0 data type shall be determined

+
+
Returns:
+

The fmi 2.0 data type, returned as string literal.n +valid fmi 2.0 data types are ‘Integer’, ‘Real’, ‘Boolean’, ‘String’ and ‘Enumeration’

+
+
Return type:
+

str

+
+
+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.graph.Graph.html b/_autosummary/ospx.graph.Graph.html new file mode 100644 index 00000000..b167a766 --- /dev/null +++ b/_autosummary/ospx.graph.Graph.html @@ -0,0 +1,591 @@ + + + + + + + + + Graph - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Graph

+
+
+class ospx.graph.Graph
+

Bases: object

+

Class providing methods to generate a visual dependency graph of a system’s components and its connections.

+
+
+__init__()
+
+ +

Methods

+
+ + + + + + + + + +

__init__()

generate_dependency_graph(case)

Generate a dependency graph of the system structure as pdf, for documentation.

+
+
+
+static generate_dependency_graph(case: OspSimulationCase) → None
+

Generate a dependency graph of the system structure as pdf, for documentation.

+

Note: This requires graphviz to be installed on the local machine

+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.graph.html b/_autosummary/ospx.graph.html new file mode 100644 index 00000000..1efaa02a --- /dev/null +++ b/_autosummary/ospx.graph.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.graph - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.graph

+

Classes

+
+ + + + + + +

Graph()

Class providing methods to generate a visual dependency graph of a system's components and its connections.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.importer.OspSystemStructureImporter.html b/_autosummary/ospx.importer.OspSystemStructureImporter.html new file mode 100644 index 00000000..6e126fb9 --- /dev/null +++ b/_autosummary/ospx.importer.OspSystemStructureImporter.html @@ -0,0 +1,609 @@ + + + + + + + + + OspSystemStructureImporter - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

OspSystemStructureImporter

+
+
+class ospx.importer.OspSystemStructureImporter
+

Bases: object

+

Class providing methods to convert an existing OspSystemStructure.xml file to an ospx caseDict file.

+
+
+__init__()
+
+ +

Methods

+
+ + + + + + + + + +

__init__()

import_system_structure(system_structure_file, *)

Import an OspSystemStructure.xml file and save it as an ospx caseDict file.

+
+
+
+static import_system_structure(system_structure_file: str | PathLike[str], *, enter_lib_source_as_relative_path: bool = False) → None
+

Import an OspSystemStructure.xml file and save it as an ospx caseDict file.

+
+
Parameters:
+
    +

  • system_structure_file (Union[str, os.PathLike[str]]) – the OspSystemStructure.xml file to be imported

    • +

  • enter_lib_source_as_relative_path (bool, optional) – whether lib_source shall be entered as relative path in the caseDict, by default False

    • +
+
+
Raises:
+
    +

  • FileNotFoundError – if system_structure_file does not exist

    • +

  • NotImplementedError – if the OspSystemStructure contains connections of OSP-IS type ‘SignalConnection’ or ‘SignalGroupConnection’. + These connection types are not implemented yet in ospx.

    • +

  • NotImplementedError – if the OspSystemStructure contains connections with OSP-IS endpoint type ‘Signal’ or ‘SignalGroup’. + These endpoint types are not implemented yet in ospx.

    • +

  • TypeError – if the OspSystemStructure contains connections of an unknown type.

    • +

  • TypeError – if the OspSystemStructure contains connections with an unknown endpoint type.

    • +
+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.importer.html b/_autosummary/ospx.importer.html new file mode 100644 index 00000000..0a4d8f97 --- /dev/null +++ b/_autosummary/ospx.importer.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.importer - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.importer

+

Classes

+
+ + + + + + +

OspSystemStructureImporter()

Class providing methods to convert an existing OspSystemStructure.xml file to an ospx caseDict file.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.ospCaseBuilder.OspCaseBuilder.html b/_autosummary/ospx.ospCaseBuilder.OspCaseBuilder.html new file mode 100644 index 00000000..19f29b7b --- /dev/null +++ b/_autosummary/ospx.ospCaseBuilder.OspCaseBuilder.html @@ -0,0 +1,615 @@ + + + + + + + + + OspCaseBuilder - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

OspCaseBuilder

+
+
+class ospx.ospCaseBuilder.OspCaseBuilder
+

Bases: object

+

Builder for OSP-specific configuration files needed to run an OSP (co-)simulation case.

+
+
+__init__() → None
+
+ +

Methods

+
+ + + + + + + + + +

__init__()

build(case_dict_file, *[, inspect, graph, clean])

Build the OSP-specific configuration files needed to run an OSP (co-)simulation case.

+
+
+
+static build(case_dict_file: str | PathLike[str], *, inspect: bool = False, graph: bool = False, clean: bool = False) → None
+

Build the OSP-specific configuration files needed to run an OSP (co-)simulation case.

+
+
Builds following files:
    +

  • OspSystemStructure.xml

    • +

  • SystemStructure.ssd

    • +

  • Plot.json

    • +

  • statisticsDict

    • +

  • watchDict

    • +
+
+
+
+
Parameters:
+
    +

  • case_dict_file (Union[str, os.PathLike[str]]) – caseDict file. Contains all case-specific information OspCaseBuilder needs to generate the OSP files.

    • +

  • inspect (bool, optional) – inspect mode. If True, build() reads all properties from the FMUs +but does not actually create the OSP case files, by default False

    • +

  • graph (bool, optional) – if True, creates a dependency graph image using graphviz, by default False

    • +

  • clean (bool, optional) – if True, cleans up case folder and deletes any formerly created ospx files, +e.g. OspSystemStructure.xml .fmu .csv etc.

    • +
+
+
Raises:
+

FileNotFoundError – if case_dict_file does not exist

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.ospCaseBuilder.html b/_autosummary/ospx.ospCaseBuilder.html new file mode 100644 index 00000000..4c657b2c --- /dev/null +++ b/_autosummary/ospx.ospCaseBuilder.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.ospCaseBuilder - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.ospCaseBuilder

+

Classes

+
+ + + + + + +

OspCaseBuilder()

Builder for OSP-specific configuration files needed to run an OSP (co-)simulation case.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.ospSimulationCase.OspSimulationCase.html b/_autosummary/ospx.ospSimulationCase.OspSimulationCase.html new file mode 100644 index 00000000..746d8294 --- /dev/null +++ b/_autosummary/ospx.ospSimulationCase.OspSimulationCase.html @@ -0,0 +1,647 @@ + + + + + + + + + OspSimulationCase - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

OspSimulationCase

+
+
+class ospx.ospSimulationCase.OspSimulationCase(case_dict: SDict[str, Any])
+

Bases: object

+

OSP Simulation Case.

+
+
+__init__(case_dict: SDict[str, Any]) → None
+
+ +

Methods

+
+ + + + + + + + + + + + + + + + + + + + + +

__init__(case_dict)

setup()

Set up the OSP simulation case folder.

write_osp_system_structure_xml()

Write the OspSystemStructure.xml file.

write_statistics_dict()

Write selected properties of the system structure into a statistics dict.

write_system_structure_ssd()

Write the SystemStructure.ssd file.

write_watch_dict()

Write a case-specific watch dict file.

+
+
+
+setup() → None
+

Set up the OSP simulation case folder.

+
+
Raises:
+
    +

  • ValueError – If an expected element in caseDict is missing

    • +

  • FileNotFoundError – If an FMU file referenced in caseDict does not exist

    • +
+
+
+
+ +
+
+write_osp_system_structure_xml() → None
+

Write the OspSystemStructure.xml file.

+
+ +
+
+write_statistics_dict() → None
+

Write selected properties of the system structure into a statistics dict.

+

I.e. for documentation or further statistical analysis.

+
+ +
+
+write_system_structure_ssd() → None
+

Write the SystemStructure.ssd file.

+
+ +
+
+write_watch_dict() → None
+

Write a case-specific watch dict file.

+
+
The watch dict file can be used with watchCosim for
    +

  • convergence control

    • +

  • convergence plotting

    • +

  • extracting the results

    • +
+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.ospSimulationCase.html b/_autosummary/ospx.ospSimulationCase.html new file mode 100644 index 00000000..bfe4f7a0 --- /dev/null +++ b/_autosummary/ospx.ospSimulationCase.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.ospSimulationCase - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.ospSimulationCase

+

Classes

+
+ + + + + + +

OspSimulationCase(case_dict)

OSP Simulation Case.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.simulation.Simulation.html b/_autosummary/ospx.simulation.Simulation.html new file mode 100644 index 00000000..0bf2c699 --- /dev/null +++ b/_autosummary/ospx.simulation.Simulation.html @@ -0,0 +1,633 @@ + + + + + + + + + Simulation - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

Simulation

+
+
+class ospx.simulation.Simulation(name: str | None = None, start_time: float | None = None, stop_time: float | None = None, base_step_size: float | None = None, _algorithm: str | None = None)
+

Bases: object

+

Data class holding the attributes of the ‘simulation’ element inside OspSystemStructure.xml.

+
+
+__init__(name: str | None = None, start_time: float | None = None, stop_time: float | None = None, base_step_size: float | None = None, _algorithm: str | None = None) → None
+
+ +

Methods

+
+ + + + + + +

__init__([name, start_time, stop_time, ...])

+
+

Attributes

+
+ + + + + + + + + + + + + + + + + + +

algorithm

Return the simulation algorithm.

base_step_size

name

start_time

stop_time

+
+
+
+property algorithm: str | None
+

Return the simulation algorithm.

+
+ +
+
+base_step_size: float | None = None
+
+ +
+
+name: str | None = None
+
+ +
+
+start_time: float | None = None
+
+ +
+
+stop_time: float | None = None
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.simulation.html b/_autosummary/ospx.simulation.html new file mode 100644 index 00000000..1ebacaa2 --- /dev/null +++ b/_autosummary/ospx.simulation.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.simulation - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.simulation

+

Classes

+
+ + + + + + +

Simulation([name, start_time, stop_time, ...])

Data class holding the attributes of the 'simulation' element inside OspSystemStructure.xml.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.system.System.html b/_autosummary/ospx.system.System.html new file mode 100644 index 00000000..87db8a09 --- /dev/null +++ b/_autosummary/ospx.system.System.html @@ -0,0 +1,699 @@ + + + + + + + + + System - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

System

+
+
+class ospx.system.System(properties: MutableMapping[Any, Any])
+

Bases: object

+

The system structure describes the topology of the co-simulated system.

+

A system structure can contain an arbitrary number of components. +Components can be connected through connections. +Connections relate a source endpoint with a target endpoint. +Both component variables and component connectors can be used as endpoints in a connection.

+
+
+__init__(properties: MutableMapping[Any, Any]) → None
+
+ +

Methods

+
+ + + + + + +

__init__(properties)

+
+

Attributes

+
+ + + + + + + + + + + + + + + + + + + + + +

components

Return a dict with all components contained in the system.

connections

Return a dict with all connections defined in the system.

connectors

Return a combined dict with all connectors from all components contained in the system.

fmus

Return a dict with all FMUs referenced by components contained in the system.

units

Return a combined dict with all units from all components contained in the system.

variables

Return a combined dict with all scalar variables from all components contained in the system.

+
+
+
+property components: dict[str, Component]
+

Return a dict with all components contained in the system.

+
+
Returns:
+

dict with all components

+
+
Return type:
+

dict[str, Component]

+
+
+
+ +
+
+property connections: dict[str, Connection]
+

Return a dict with all connections defined in the system.

+
+
Returns:
+

dict with all connections

+
+
Return type:
+

dict[str, Connection]

+
+
+
+ +
+
+property connectors: dict[str, Connector]
+

Return a combined dict with all connectors from all components contained in the system.

+
+
Returns:
+

dict with all connectors from all components

+
+
Return type:
+

dict[str, Connector]

+
+
+
+ +
+
+property fmus: dict[str, FMU]
+

Return a dict with all FMUs referenced by components contained in the system.

+
+
Returns:
+

dict with all FMUs

+
+
Return type:
+

dict[str, FMU]

+
+
+
+ +
+
+property units: dict[str, Unit]
+

Return a combined dict with all units from all components contained in the system.

+
+
Returns:
+

dict with all units from all components

+
+
Return type:
+

dict[str, Unit]

+
+
+
+ +
+
+property variables: dict[str, ScalarVariable]
+

Return a combined dict with all scalar variables from all components contained in the system.

+
+
Returns:
+

dict with all scalar variables from all components

+
+
Return type:
+

dict[str, ScalarVariable]

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.system.html b/_autosummary/ospx.system.html new file mode 100644 index 00000000..2256ed9d --- /dev/null +++ b/_autosummary/ospx.system.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.system - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.system

+

Classes

+
+ + + + + + +

System(properties)

The system structure describes the topology of the co-simulated system.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.utils.dateTime.html b/_autosummary/ospx.utils.dateTime.html new file mode 100644 index 00000000..39ac54d2 --- /dev/null +++ b/_autosummary/ospx.utils.dateTime.html @@ -0,0 +1,591 @@ + + + + + + + + + ospx.utils.dateTime - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.utils.dateTime

+

Functions

+
+ + + + + + +

calc_time(time0, time1)

Calculate the time delta between time0 and time1.

+
+
+
+ospx.utils.dateTime.calc_time(time0: datetime, time1: datetime) → tuple[int, int, int, int, int]
+

Calculate the time delta between time0 and time1.

+

Calculates the time delta between time0 and time1 and +returns the result as a tuple of integers representing the number of +months, days, hours, minutes and seconds +the time delta constitutes.

+
+
Parameters:
+
    +

  • time0 (datetime) – start time

    • +

  • time1 (datetime) – end time

    • +
+
+
Returns:
+

tuple of integers representing the number of +months, days, hours, minutes and seconds +the time delta constitutes.

+
+
Return type:
+

Tuple[int, int, int, int, int]

+
+
+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.utils.dict.html b/_autosummary/ospx.utils.dict.html new file mode 100644 index 00000000..b830d59b --- /dev/null +++ b/_autosummary/ospx.utils.dict.html @@ -0,0 +1,603 @@ + + + + + + + + + ospx.utils.dict - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.utils.dict

+

Functions

+
+ + + + + + + + + + + + + + + +

find_key(dict_in, pattern)

Find the first key in dict that matches the given pattern.

find_keys(dict_in, pattern)

Find all keys in dict that match the given pattern.

find_type_identifier_in_keys(dict_in)

Find the first type identifier in dict.

shrink_dict(dict_in[, unique_key])

Identify doubled entries in the passed in dict and return a new dict with doubled entries removed.

+
+
+
+ospx.utils.dict.find_key(dict_in: MutableMapping[Any, Any], pattern: str) → str | None
+

Find the first key in dict that matches the given pattern.

+
+ +
+
+ospx.utils.dict.find_keys(dict_in: MutableMapping[Any, Any], pattern: str) → list[str] | None
+

Find all keys in dict that match the given pattern.

+
+ +
+
+ospx.utils.dict.find_type_identifier_in_keys(dict_in: MutableMapping[Any, Any]) → str | None
+

Find the first type identifier in dict.

+

Find. the first key name in dict that contains one of the following type identifier strings: +[Integer|Real|Boolean|Enumeration|String|Unknown].

+
+ +
+
+ospx.utils.dict.shrink_dict(dict_in: MutableMapping[Any, Any], unique_key: list[str] | None = None) → dict[Any, Any]
+

Identify doubled entries in the passed in dict and return a new dict with doubled entries removed.

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.utils.html b/_autosummary/ospx.utils.html new file mode 100644 index 00000000..811b3a1c --- /dev/null +++ b/_autosummary/ospx.utils.html @@ -0,0 +1,558 @@ + + + + + + + + + ospx.utils - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+ +
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.utils.logging.html b/_autosummary/ospx.utils.logging.html new file mode 100644 index 00000000..751dd200 --- /dev/null +++ b/_autosummary/ospx.utils.logging.html @@ -0,0 +1,587 @@ + + + + + + + + + ospx.utils.logging - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.utils.logging

+

Functions to configure logging for the application.

+

Functions

+
+ + + + + + +

configure_logging([log_level_console, ...])

Configure logging for the application, allowing for both console and file logging.

+
+
+
+ospx.utils.logging.configure_logging(log_level_console: str = 'WARNING', log_file: Path | None = None, log_level_file: str = 'WARNING') → None
+

Configure logging for the application, allowing for both console and file logging.

+

Sets the log levels and formats for the output, ensuring that logs are captured as specified.

+
+
Parameters:
+
    +

  • log_level_console (str, optional) – log level for console output, by default “WARNING”

    • +

  • log_file (Path | None, optional) – log file to be used. If None, file logging is disabled. by default None

    • +

  • log_level_file (str, optional) – log level for file output, by default “WARNING”

    • +
+
+
Raises:
+

TypeError – if an invalid value for log_level_console or log_level_file is passed

+
+
+

Examples

+

configure_logging(log_level_console=”INFO”, log_file=Path(“app.log”), log_level_file=”DEBUG”)

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.utils.plotting.html b/_autosummary/ospx.utils.plotting.html new file mode 100644 index 00000000..031094c9 --- /dev/null +++ b/_autosummary/ospx.utils.plotting.html @@ -0,0 +1,603 @@ + + + + + + + + + ospx.utils.plotting - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.utils.plotting

+

Functions

+
+ + + + + + + + + +

create_meta_dict(title)

Create a default of meta dict which can be passed to save_figure().

save_figure(fig, extension, path, title, ...)

Save a figure object as image file.

+
+
+
+ospx.utils.plotting.create_meta_dict(title: str) → dict[str, str]
+

Create a default of meta dict which can be passed to save_figure().

+
+
Parameters:
+

title (str) – the title of the figure

+
+
Returns:
+

the meta dict

+
+
Return type:
+

Dict[str, str]

+
+
+
+ +
+
+ospx.utils.plotting.save_figure(fig: Figure, extension: str, path: str | PathLike[str], title: str, meta_dict: MutableMapping[str, str]) → None
+

Save a figure object as image file.

+
+
Parameters:
+
    +

  • fig (Figure) – the Matplotlib figure object

    • +

  • extension (str) – the file extension. Determines the file format.

    • +

  • path (Union[str, os.PathLike[str]]) – the folder to save the file in

    • +

  • title (str) – image title. Will also be used as file name.

    • +

  • meta_dict (MutableMapping[str, str]) – a dict with additional meta properties. Will be passed as-is to figure.savefig()

    • +
+
+
+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.utils.zip.html b/_autosummary/ospx.utils.zip.html new file mode 100644 index 00000000..99f81301 --- /dev/null +++ b/_autosummary/ospx.utils.zip.html @@ -0,0 +1,627 @@ + + + + + + + + + ospx.utils.zip - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.utils.zip

+

Functions

+
+ + + + + + + + + + + + + + + + + + + + + +

add_file_content_to_zip(zip_file, file_name, ...)

Add a single file and its ascii content.

read_file_content_from_zip(zip_file, file_name)

Read a single file.

remove_files_from_zip(zip_file, *file_names)

Remove files.

rename_file_in_zip(zip_file, file_name, ...)

Rename files.

substitute_text_in_zip(zip_file[, ...])

Substitute a given string in all files matching the passed file name pattern.

update_file_content_in_zip(zip_file, ...)

Update the ascii content of a single file.

+
+
+
+ospx.utils.zip.add_file_content_to_zip(zip_file: Path, file_name: str, file_content: str) → ZipFile | None
+

Add a single file and its ascii content.

+

Belongs to zip functions.

+
+ +
+
+ospx.utils.zip.read_file_content_from_zip(zip_file: Path, file_name: str) → str | None
+

Read a single file.

+

Belongs to zip functions

+
+ +
+
+ospx.utils.zip.remove_files_from_zip(zip_file: Path, *file_names: str) → ZipFile | None
+

Remove files.

+

Belongs to zip functions.

+
+ +
+
+ospx.utils.zip.rename_file_in_zip(zip_file: Path, file_name: str, new_file_name: str) → ZipFile | None
+

Rename files.

+

Belongs to zip functions.

+
+ +
+
+ospx.utils.zip.substitute_text_in_zip(zip_file: Path, file_name_pattern: str = '', subst: tuple[str, str] = ('', '')) → ZipFile | None
+

Substitute a given string in all files matching the passed file name pattern.

+

Belongs to zip functions.

+
+ +
+
+ospx.utils.zip.update_file_content_in_zip(zip_file: Path, file_name: str, file_content: str) → ZipFile | None
+

Update the ascii content of a single file.

+

Belongs to zip functions.

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.watch.cli.html b/_autosummary/ospx.watch.cli.html new file mode 100644 index 00000000..a2883ced --- /dev/null +++ b/_autosummary/ospx.watch.cli.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.watch.cli - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.watch.cli

+

Modules

+
+ + + + + + +

watchCosim

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.watch.cli.watchCosim.html b/_autosummary/ospx.watch.cli.watchCosim.html new file mode 100644 index 00000000..63353d33 --- /dev/null +++ b/_autosummary/ospx.watch.cli.watchCosim.html @@ -0,0 +1,572 @@ + + + + + + + + + ospx.watch.cli.watchCosim - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.watch.cli.watchCosim

+

Functions

+
+ + + + + + +

main()

Entry point for console script as configured in setup.cfg.

+
+
+
+ospx.watch.cli.watchCosim.main() → None
+

Entry point for console script as configured in setup.cfg.

+

Runs the command line interface and parses arguments and options entered on the console.

+
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.watch.html b/_autosummary/ospx.watch.html new file mode 100644 index 00000000..62b42500 --- /dev/null +++ b/_autosummary/ospx.watch.html @@ -0,0 +1,549 @@ + + + + + + + + + ospx.watch - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+ +
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.watch.watchCosim.CosimWatcher.html b/_autosummary/ospx.watch.watchCosim.CosimWatcher.html new file mode 100644 index 00000000..5197fd9d --- /dev/null +++ b/_autosummary/ospx.watch.watchCosim.CosimWatcher.html @@ -0,0 +1,627 @@ + + + + + + + + + CosimWatcher - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

CosimWatcher

+
+
+class ospx.watch.watchCosim.CosimWatcher(csv_file_names: MutableSequence[str], skip_values: int, latest_values: int, scale_factor: float, *, timeline_data: bool)
+

Bases: object

+

Watcher to monitor a running simulation.

+

CosimWatcher allows to monitor a running simulation, +plot trends and dump simulation results into a resultDict file.

+
+
+__init__(csv_file_names: MutableSequence[str], skip_values: int, latest_values: int, scale_factor: float, *, timeline_data: bool) → None
+
+ +

Methods

+
+ + + + + + + + + + + + + + + +

__init__(csv_file_names, skip_values, ...)

dump()

Write dataframe to dump.

plot(*[, converge])

Plot trends.

read_watch_dict(watch_dict_file)

Read watchDict file.

+
+
+
+dump() → None
+

Write dataframe to dump.

+
+ +
+
+plot(*, converge: bool = False) → None
+

Plot trends.

+

Plotting + convergence checker (future task)

+
+
Parameters:
+

converge (bool, optional) – if True, convergence is checked, by default False

+
+
+
+ +
+
+read_watch_dict(watch_dict_file: str | PathLike[str]) → None
+

Read watchDict file.

+

The watchDict file contains the parameters to be plotted.

+
+
Parameters:
+

watch_dict_file (Union[str, os.PathLike[str]]) – watchDict file. Contains the parameters to be plotted.

+
+
Raises:
+

FileNotFoundError – if watch_dict_file does not exist

+
+
+
+ +
+ +
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_autosummary/ospx.watch.watchCosim.html b/_autosummary/ospx.watch.watchCosim.html new file mode 100644 index 00000000..d00b9a65 --- /dev/null +++ b/_autosummary/ospx.watch.watchCosim.html @@ -0,0 +1,546 @@ + + + + + + + + + ospx.watch.watchCosim - farn 0.4.0 + + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
farn 0.4.0
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ + + + +
+
+ +
+ +
+
+
+

ospx.watch.watchCosim

+

Classes

+
+ + + + + + +

CosimWatcher(csv_file_names, skip_values, ...)

Watcher to monitor a running simulation.

+
+
+ +
+
+ +
+ +
+
+ + + + + \ No newline at end of file diff --git a/_images/demoCase.png b/_images/demoCase.png new file mode 100644 index 00000000..1b073884 Binary files /dev/null and b/_images/demoCase.png differ diff --git a/_sources/CHANGELOG.md.txt b/_sources/CHANGELOG.md.txt new file mode 100644 index 00000000..b76750e4 --- /dev/null +++ b/_sources/CHANGELOG.md.txt @@ -0,0 +1,2 @@ +```{include} ../../CHANGELOG.md +``` \ No newline at end of file diff --git a/_sources/CHANGELOG_dictIO.md.txt b/_sources/CHANGELOG_dictIO.md.txt new file mode 100644 index 00000000..c0aa8d80 --- /dev/null +++ b/_sources/CHANGELOG_dictIO.md.txt @@ -0,0 +1,370 @@ +# dictIO + +All notable changes to the [dictIO] project will be documented in this file.
+The changelog format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +## [Unreleased] + +-/- + + +## [0.4.0] - 2024-11-11 + +### Breaking changes +* Renamed modules: Following modules have been renamed in order to comply with PEP8 naming conventions:
+ `dictIO.dictReader` **->** `dictIO.dict_reader`
+ `dictIO.dictWriter` **->** `dictIO.dict_writer`
+ `dictIO.dictParser` **->** `dictIO.dict_parser`
+ `dictIO.cppDict` **->** `dictIO.cpp_dict`
+* Module `formatter.py` :
+ Renamed `Formatter.format_type()` **->** `Formatter.format_value()`
+* Module `parser.py` :
+ Renamed `Parser.parse_type()` **->** `Parser.parse_value()`
+ Renamed `Parser.parse_types()` **->** `Parser.parse_values()`
+* class `CppDict` in module `dictIO.cppDict` has been replaced with the new class `SDict[K, V]` in module `dictIO.dict`.
+ In order to maintain backward compatibility, a thin wrapper class named `CppDict` is kept in version ~0.4.0. + It is marked as deprecated, though, and will be removed with release 0.5.0. +* Where `CppDict` inherited from `UserDict`, `SDict` inherits directly from Python's `dict` class, + allowing to use it in any context where a `dict` or any other `MutableMapping` is expected. +* `SDict` is generic: Static type checkers will hence require type arguments when `SDict` is used.
+ Where in dictIO < 0.4.0 you could write
+ `my_dict: CppDict = CppDict()`,
+ you will now need to specify the type arguments, e.g.
+ `my_dict: SDict[str, Any] = SDict()`.
+ With this change, type hinting is in line with how Python's builtin `dict` class works, and offers more control in static type checking. + +### Changed +* Changed from `pip`/`tox` to `uv` as package manager +* README.md : Completely rewrote section "Development Setup", introducing `uv` as package manager. +* Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI +* Updated copyright statement +* VS Code settings: Turned off automatic venv activation +* Replaced black formatter with ruff formatter + +### Solved +* Sphinx documentation: Resolved issue that documentation of class members was generated twice. + +### Added +* Sphinx documentation: Added extension to support Markdown-based diagrams created with Mermaid. +* Added instance methods `dump()` and `load()` to `SDict` +* Added `mypy` as static type checker (in addition to `pyright`) + +### GitHub workflows +* (all workflows): Adapted to use `uv` as package manager +* _test_future.yml : updated Python version to 3.13.0-alpha - 3.13.0 +* _test_future.yml : updated name of test job to 'test313' + +### Dependencies +* Updated to ruff>=0.6.3 (from ruff==0.4.2) +* Updated to pyright>=1.1.378 (from pyright==1.1.360) +* Updated to sourcery>=1.22 (from sourcery==1.16) +* Updated to pytest>=8.3 (from pytest>=8.2) +* Updated to Sphinx>=8.0 (from Sphinx>=7.3) +* Updated to sphinx-argparse-cli>=1.17 (from sphinx-argparse-cli>=1.16) +* Updated to myst-parser>=4.0 (from myst-parser>=3.0) +* Updated to furo>=2024.8 (from furo>=2024.5) +* updated to setup-python@v5 (from setup-python@v4) +* updated to actions-gh-pages@v4 (from actions-gh-pages@v3) +* updated to upload-artifact@v4 (from upload-artifact@v3) +* Updated to download-artifact@v4 (from download-artifact@v3) +* updated to checkout@v4 (from checkout@v3) + + +## [0.3.4] - 2024-05-22 + +### Dependencies +* updated to ruff==0.4.2 (from ruff==0.2.1) +* updated to pyright==1.1.360 (from pyright==1.1.350) +* updated to sourcery==1.16 (from sourcery==1.15) +* updated to lxml>=5.2 (from lxml>=5.1) +* updated to types-lxml>=2024.4 (from types-lxml>=5.1) +* updated to pytest>=8.2 (from pytest>=7.4) +* updated to pytest-cov>=5.0 (from pytest-cov>=4.1) +* updated to Sphinx>=7.3 (from Sphinx>=7.2) +* updated to sphinx-argparse-cli>=1.15 (from sphinx-argparse-cli>=1.11) +* updated to myst-parser>=3.0 (from myst-parser>=2.0) +* updated to furo>=2024.4 (from furo>=2023.9.10) +* updated to numpy>=1.26,<2.0 (from numpy>=1.26) +* removed black + +### Changed +* replaced black formatter with ruff formatter +* Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI +* Updated copyright statement +* VS Code settings: Turned off automatic venv activation + + +## [0.3.3] - 2024-02-21 + +### Hotfix +* corrected name of cli script (wrong: dictIO correct: dictParser) + + +## [0.3.2] - 2024-02-21 + +### Added +* README.md : Under `Development Setup`, added a step to install current package in "editable" mode, using the pip install -e option. +This removes the need to manually add /src to the PythonPath environment variable in order for debugging and tests to work. + +### Removed +* VS Code settings: Removed the setting which added the /src folder to PythonPath. This is no longer necessary. Installing the project itself as a package in "editable" mode, using the pip install -e option, solves the issue and removes the need to manually add /src to the PythonPath environment variable. + +### Changed +* Moved all project configuration from setup.cfg to pyproject.toml +* Moved all tox configuration from setup.cfg to tox.ini. +* Moved pytest configuration from pyproject.toml to pytest.ini +* Deleted setup.cfg + +### Dependencies +* updated to black[jupyter]==24.1 (from black[jupyter]==23.12) +* updated to version: '==24.1' (from version: '==23.12') +* updated to ruff==0.2.1 (from ruff==0.1.8) +* updated to pyright==1.1.350 (from pyright==1.1.338) +* updated to sourcery==1.15 (from sourcery==1.14) +* updated to lxml>=5.1 (from lxml>=4.9) + + +## [0.3.1] - 2024-01-09 + +### Solved + +* Solved a bug that led to single character references not being identified + (solves [#14](https://github.com/dnv-opensource/dictIO/issues/14)). + + +## [0.3.0] - 2024-01-08 + +### Changed + +* Enabled recognition of strings with nested quotes in it (solves [#2](https://github.com/dnv-opensource/dictIO/issues/2)) +* GitHub workflows: Included Python 3.12 release version as standard, and Python 3.13.0a2 as "future" test. + +### Dependencies + +* updated to black[jupyter]==23.12 (from black[jupyter]==23.11) +* updated to ruff==0.1.8 (from ruff==0.1.6) +* updated to pyright==1.1.338 (from pyright==1.1.336) + + +## [0.2.9] - 2023-09-20 + +### Dependencies + +* Updated dependencies to latest versions + + +## [0.2.8] - 2023-06-22 + +### Changed + +* Modularized GitHub workflows +* Changed default Python version in GitHub workflows from 3.10 to 3.11 + +### Dependencies + +* requirements-dev.txt: Updated dependencies to latest versions + + +## [0.2.7] - 2023-05-04 + +### Changed + +* dependencies: updated dependencies to latest versions +* ruff: added rule-set "B" (flake8-bugbear) + + +## [0.2.6] - 2023-01-11 + +### Changed + +* Added missing DocStrings for public classes, methods and functions +* Changed links to package documentation to open README.html, not the default index page + + +## [0.2.5] - 2023-01-04 + +### Changed + +* Linter: Migrated from flake8 to ruff.
+ (Added ruff; removed flake8 and isort) +* Adjusted GitHub CI workflow accordingly.
+ (Added ruff job; removed flake8 and isort jobs) +* VS Code settings: Adjusted Pylance configuration +* Sphinx documentation: Rebuilt API documentation + +### Added + +* Added a batch file 'qa.bat' in root folder to ease local execution of code quality checks + + +## [0.2.4] - 2022-12-12 + +### Changed + +* Moved dev-only dependencies from requirements.txt to requirements-dev.txt +* dictIO/`__utils__`.py : ensured that imported symbols get also exported
+ (added "as" clause -> "from x import y as y" instead of only "from x import y") +* Configured code quality tools flake8, black, isort, pyright +* Improved code quality, resolving all warnings and errors flagged by the configured code quality tools + (flake8, black, isort, pyright, sourcery) + +### Added + +* Added support for selected numpy functions (diag, eye, ones, zeros) + which can now be used in expressions.
+ This is an experimental feature which might be removed or changed in future. +* Added GitHub workflow 'main.yml' for continuous integration (runs all CI tasks except Sphinx) + * format checks: black, isort + * lint check: flake8, flake8-bugbear + * type check: pyright + * test: uses tox to run pytest on {Windows, Linux, MacOS} with {py39, py310} + * publish: publishing to PyPI (runs only on push of new tag vx.x.x, and after all other jobs succeeded) + * merge_to_release_branch: merge tagged commit to release branch (runs after publish) + + +## [0.2.3] - 2022-12-01 + +### Changed + +* Code formatting: Changed from yapf to black +* STYLEGUIDE.md : Adjusted to match black formatting +* VS Code settings: Updated to use black as formatter +* requirements.txt: Updated dependencies to their most recent versions +* GitHub actions (yml files): Updated following actions to their most recent versions: + * checkout@v1 -> checkout@v3 + * setup-python@v2 -> setup-python@v4 + * cache@v2 -> cache@v3 + +### Added + +* Added sourcery configuration (.sourcery.yaml) +* Added py.typed file into the package root folder and included it setup.cfg as package_data +* Documentation: Included sub-package dictIO.utils in documentation + + +## [0.2.2] - 2022-11-08 + +### Added + +* JsonParser: JsonParser now supports the usage of references and expressions, similar to the CppParser. + +## [0.2.1] - 2022-10-13 + +### Solved + +* XmlParser: Solved a bug where default namespaces in an XML file would not be parsed correctly. + +## [0.2.0] - 2022-09-29 + +### Added + +* dictIO.utils.path.py: Added two new functions + * highest_common_root_folder(paths) + * relative_path(from_path, to_path) + +### Changed + +* Replaced usages of pathlib.Path.resolve_to() with dictIO.utils.path.relative_path() + +### Removed + +* dictIO.utils.path.py: Removed obsolete function silent_remove() + + +## [0.1.2] - 2022-09-27 + +### Solved + +* XmlParser: Changed how empty XML nodes get parsed.
+ The value for an empty node is now saved as an empty dict, i.e. {}, instead of None. + This change solves [issue #4](https://github.com/dnv-opensource/dictIO/issues/4).
+ Problem was that None is not iterable, and code such as the following had caused an exception: + ~~~py + if '_attributes' in my_parsed_xml_dict[node_key]: + ... + ~~~ + because my_parsed_xml_dict[node_key] had been None. + + Now, with the code change in place, my_parsed_xml_dict[node_key] would resolve to an empty dict ( {} ) instead of to None. As a dict is formally iterable (even when empty), querying code as above does no longer crash. + + +## [0.1.1] - 2022-08-19 + +### Added + +* cppDict: + * Added method include(dict_to_include). + This method adds an include directive for the passed in dict inside the dict the method is called on. + + +## [0.1.0] - 2022-05-28 + +### Changed + +* Simplified imports from namespace dictIO. Example: + * Old (<= v0.0.22): + ~~~py + from dictIO.dictParser import DictParser + ~~~ + * New: + ~~~py + from dictIO import DictParser + ~~~ + +* parser.py + * Parser.remove_quotes_from_string() + * Changed default of 'all' argument from True to False
+ This change was introduced in order to, by default, protect inner quotes in i.e. a farn filter expression "var in ['item1', 'item2']" from being removed. + + * CppParser._parse_tokenized_dict() + * Changed implementation of the conditional code where a key value pair gets parsed.
+ This change was introduced in order to better identify invalid key value pairs.
+ Two invalid keys were added in test_parser_dict (section 'invalid') and a respective test was added. + +* formatter.py + * JsonFormatter.insert_includes() + * Changed correction of backslashes, so that backslashes in include paths are not substituted by forwardslashes but actually escaped in Json compliant way. + +* dictWriter.py + * DictWriter.write() + * Changed default of 'mode' argument from 'w' (overwrite) to 'a' (append) + +* utils\strings.py + * plural() function moved to farn package (-> moved into utils\logging.py module in farn)
+ It was moved since the plural() function is currently used in farn logging only (neither in dictIO nor in ospx). + + +## [0.0.22] - 2022-05-09 + +* First public release + +## [0.0.17] - 2022-02-14 + +### Added + +* Added support for Python 3.10 + + +[unreleased]: https://github.com/dnv-opensource/dictIO/compare/v0.4.0...HEAD +[0.4.0]: https://github.com/dnv-opensource/dictIO/compare/v0.3.4...v0.4.0 +[0.3.4]: https://github.com/dnv-opensource/dictIO/compare/v0.3.3...v0.3.4 +[0.3.3]: https://github.com/dnv-opensource/dictIO/compare/v0.3.2...v0.3.3 +[0.3.2]: https://github.com/dnv-opensource/dictIO/compare/v0.3.1...v0.3.2 +[0.3.1]: https://github.com/dnv-opensource/dictIO/compare/v0.3.0...v0.3.1 +[0.3.0]: https://github.com/dnv-opensource/dictIO/compare/v0.2.9...v0.3.0 +[0.2.9]: https://github.com/dnv-opensource/dictIO/compare/v0.2.8...v0.2.9 +[0.2.8]: https://github.com/dnv-opensource/dictIO/compare/v0.2.7...v0.2.8 +[0.2.7]: https://github.com/dnv-opensource/dictIO/compare/v0.2.6...v0.2.7 +[0.2.6]: https://github.com/dnv-opensource/dictIO/compare/v0.2.5...v0.2.6 +[0.2.5]: https://github.com/dnv-opensource/dictIO/compare/v0.2.4...v0.2.5 +[0.2.4]: https://github.com/dnv-opensource/dictIO/compare/v0.2.3...v0.2.4 +[0.2.3]: https://github.com/dnv-opensource/dictIO/compare/v0.2.2...v0.2.3 +[0.2.2]: https://github.com/dnv-opensource/dictIO/compare/v0.2.1...v0.2.2 +[0.2.1]: https://github.com/dnv-opensource/dictIO/compare/v0.2.0...v0.2.1 +[0.2.0]: https://github.com/dnv-opensource/dictIO/compare/v0.1.2...v0.2.0 +[0.1.2]: https://github.com/dnv-opensource/dictIO/compare/v0.1.1...v0.1.2 +[0.1.1]: https://github.com/dnv-opensource/dictIO/compare/v0.1.0...v0.1.1 +[0.1.0]: https://github.com/dnv-opensource/dictIO/compare/v0.0.22...v0.1.0 +[0.0.22]: https://github.com/dnv-opensource/dictIO/compare/v0.0.17...v0.0.22 +[0.0.17]: https://github.com/dnv-opensource/dictIO/releases/tag/v0.0.17 +[dictIO]: https://github.com/dnv-opensource/dictIO diff --git a/_sources/CHANGELOG_farn.md.txt b/_sources/CHANGELOG_farn.md.txt new file mode 100644 index 00000000..1ef2a6bb --- /dev/null +++ b/_sources/CHANGELOG_farn.md.txt @@ -0,0 +1,414 @@ +# farn + +All notable changes to the [farn] project will be documented in this file.
+The changelog format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +## [Unreleased] + +-/- + + +## [0.4.0] - 2024-11-11 + +### Breaking changes +* The code has been adapted to [dictIO][dictIO_docs] 0.4.0
+ [dictIO][dictIO_docs] 0.4.0 introduced some breaking changes. With the current release 0.4.0 of farn, the code base has been adapted to these in changes.
+ The most prominent change being that class `dictIO.CppDict` has been replaced by class `dictIO.SDict`. + +### Changed +* Changed from `pip`/`tox` to `uv` as package manager +* README.md : Completely rewrote section "Development Setup", introducing `uv` as package manager. +* Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI +* Updated copyright statement +* VS Code settings: Turned off automatic venv activation +* Replaced black formatter with ruff formatter + +### Solved +* Sphinx documentation: Resolved issue that documentation of class members was generated twice. + +### Added +* Sphinx documentation: Added extension to support Markdown-based diagrams created with Mermaid. +* Added `mypy` as static type checker (in addition to `pyright`) + +### GitHub workflows +* (all workflows): Adapted to use `uv` as package manager +* _test_future.yml : updated Python version to 3.13.0-alpha - 3.13.0 +* _test_future.yml : updated name of test job to 'test313' + +### Dependencies +* Updated to dictIO>=0.4.0 (from dictIO>=0.3.4) +* Updated to ospx>=0.3.0 (from ospx>=0.2.14) +* Updated to ruff>=0.6.3 (from ruff==0.4.2) +* Updated to pyright>=1.1.378 (from pyright==1.1.360) +* Updated to sourcery>=1.22 (from sourcery==1.16) +* Updated to pytest>=8.3 (from pytest>=8.2) +* Updated to Sphinx>=8.0 (from Sphinx>=7.3) +* Updated to sphinx-argparse-cli>=1.17 (from sphinx-argparse-cli>=1.16) +* Updated to myst-parser>=4.0 (from myst-parser>=3.0) +* Updated to furo>=2024.8 (from furo>=2024.5) +* updated to setup-python@v5 (from setup-python@v4) +* updated to actions-gh-pages@v4 (from actions-gh-pages@v3) +* updated to upload-artifact@v4 (from upload-artifact@v3) +* Updated to download-artifact@v4 (from download-artifact@v3) +* updated to checkout@v4 (from checkout@v3) + + +## [0.3.7] - 2024-05-22 + +### Dependencies +* updated to ruff==0.4.2 (from ruff==0.2.1) +* updated to pyright==1.1.360 (from pyright==1.1.350) +* updated to sourcery==1.16 (from sourcery==1.15) +* updated to lxml>=5.2 (from lxml>=5.1) +* updated to types-lxml>=2024.4 (from types-lxml>=5.1) +* updated to scipy>=1.13 (from scipy>=1.12) +* updated to Pillow>=10.3 (from Pillow>=10.2) +* updated to pytest>=8.2 (from pytest>=7.4) +* updated to pytest-cov>=5.0 (from pytest-cov>=4.1) +* updated to Sphinx>=7.3 (from Sphinx>=7.2) +* updated to sphinx-argparse-cli>=1.15 (from sphinx-argparse-cli>=1.11) +* updated to myst-parser>=3.0 (from myst-parser>=2.0) +* updated to furo>=2024.4 (from furo>=2023.9.10) +* updated to dictIO>=0.3.4 (from dictIO>=0.3.3) +* updated to ospx>=0.2.14 (from ospx>=0.2.13) +* updated to numpy>=1.26,<2.0 (from numpy>=1.26) +* updated to matplotlib>=3.9 (from matplotlib>=3.8) +* removed black + +### Changed +* replaced black formatter with ruff formatter +* Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI +* Updated copyright statement +* VS Code settings: Turned off automatic venv activation + +### Added +* `farn.core.case.Case`: Added method `add_parameters()`, which allows to manually add user-defined parameters to a Case. + + +## [0.3.6] - 2024-02-21 + +### Added +* README.md : Under `Development Setup`, added a step to install current package in "editable" mode, using the pip install -e option. +This removes the need to manually add /src to the PythonPath environment variable in order for debugging and tests to work. + +### Removed +* VS Code settings: Removed the setting which added the /src folder to PythonPath. This is no longer necessary. Installing the project itself as a package in "editable" mode, using the pip install -e option, solves the issue and removes the need to manually add /src to the PythonPath environment variable. + +### Changed +* Moved all project configuration from setup.cfg to pyproject.toml +* Moved all tox configuration from setup.cfg to tox.ini. +* Moved pytest configuration from pyproject.toml to pytest.ini +* Deleted setup.cfg + +### Dependencies +* updated to black[jupyter]==24.1 (from black[jupyter]==23.12) +* updated to version: '==24.1' (from version: '==23.12') +* updated to ruff==0.2.1 (from ruff==0.1.8) +* updated to pyright==1.1.350 (from pyright==1.1.338) +* updated to sourcery==1.15 (from sourcery==1.14) +* updated to lxml>=5.1 (from lxml>=4.9) +* updated to scipy>=1.12 (from scipy>=1.11) +* updated to pandas>=2.2 (from pandas>=2.1) +* updated to Pillow>=10.2 (from Pillow>=10.1) + +* -/- + + +## [0.3.5] - 2024-01-09 + +### Changed + +* farn/sampling/sampling.py: + * _generate_values_using_uniform_lhs_sampling(): + replaced SALib latin with pyDOE2 lhs + * _generate_values_using_sobol_sampling(): + replaced sobol-seq with scipy.stats.qmc.sobol + * removed orphaned _cov argument from normalLhs sampling + +### Dependencies + +* Upgraded from pyDOE2>=1.3 to pyDOE3>=1.0 +* Removed SALib and sobol-seq +* Updated to dictIO>=0.3.1 and ospx>=0.2.12 +* Updated other dependencies to latest versions + + +## [0.3.4] - 2023-09-25 + +### Dependencies + +* Updated dependencies to latest versions + + +## [0.3.3] - 2023-06-22 + +### Changed + +* Modularized GitHub workflows +* Changed default Python version in GitHub workflows from 3.10 to 3.11 + +### Dependencies + +* updated to dictIO>=0.2.8 and ospx>=0.2.10 +* requirements-dev.txt: Updated dependencies to latest versions + + +## [0.3.2] - 2023-05-04 + +### Changed + +* dependencies: updated dependencies to latest versions + + +## [0.3.1] - 2023-01-11 + +### Changed + +* Added missing DocStrings for public classes, methods and functions +* Changed links to package documentation to open README.html, not the default index page +* data classes: changed initialisation of mutable types to use default_factory +* ruff: added rule-set "B" (flake8-bugbear) + +### Dependencies + +* updated to dictIO>=0.2.6 and ospx>=0.2.8 + + +## [0.3.0] - 2023-01-09 + +v0.3.0 is a major update comprising one breaking change (see below). +Users are encouraged to update to this version. + +### Breaking Change + +* Moved classes 'Case' and 'Parameter' from farn.farn to farn.core
+ As a consequence, if you imported these classes in your code, you need to + adapt the respective import statements. I.e.
+ old + ~~~py + from farn.farn import Case, Parameter + ~~~ + new + ~~~py + from farn.core import Case, Parameter + ~~~ + +### Added + +* Added a 'Cases' class, acting as a container for Case instances. + Cases inherits from List[Case] and can hence transparently be used as a Python list type. + However, Cases provides additional convenience methods to export the attributes of all contained Case instances to a pandas DataFrame (Cases.to_pandas()) or to a numpy ndarray (Cases.to_numpy())

+ Cases is located in the farn.core sub-package and can be imported from there, i.e: + ~~~py + from farn.core import Case, Cases, Parameter + ~~~ + + +## [0.2.7] - 2023-01-04 + +### Changed + +* Linter: Migrated from flake8 to ruff.
+ (Added ruff; removed flake8 and isort) +* Adjusted GitHub CI workflow accordingly.
+ (Added ruff job; removed flake8 and isort jobs) +* VS Code settings: Adjusted Pylance configuration + +### Added + +* Added a batch file 'qa.bat' in root folder to ease local execution of code quality checks + +### Dependencies + +* updated to dictIO>=0.2.5 and ospx>=0.2.7 + + +## [0.2.6] - 2022-12-12 + +### Dependencies + +* updated to ospx>=0.2.6 + +## [0.2.5] - 2022-12-12 + +### Changed + +* Moved dev-only dependencies from requirements.txt to requirements-dev.txt +* farn/`__init__`.py : ensured that imported symbols get also exported
+ (added "as" clause -> "from x import y as y" instead of only "from x import y") +* sampling.py: refactored for cleaner code +* Configured code quality tools flake8, black, isort, pyright +* Improved code quality, resolving all warnings and errors flagged by the configured code quality tools + (flake8, black, isort, pyright, sourcery) + +### Added + +* Added GitHub workflow 'main.yml' for continuous integration (runs all CI tasks except Sphinx) + * format checks: black, isort + * lint check: flake8, flake8-bugbear + * type check: pyright + * test: uses tox to run pytest on {Windows, Linux, MacOS} with {py39, py310} + * publish: publishing to PyPI (runs only on push of new tag vx.x.x, and after all other jobs succeeded) + * merge_to_release_branch: merge tagged commit to release branch (runs after publish) + +### Dependencies + +* updated to dictIO>=0.2.4 + +## [0.2.4] - 2022-12-01 + +### Changed + +* Code formatting: Changed from yapf to black +* STYLEGUIDE.md : Adjusted to match black formatting +* VS Code settings: Updated to use black as formatter +* requirements.txt: Updated dependencies to their most recent versions +* GitHub actions (yml files): Updated following actions to their most recent versions: + * checkout@v1 -> checkout@v3 + * setup-python@v2 -> setup-python@v4 + * cache@v2 -> cache@v3 + +### Added + +* Added sourcery configuration (.sourcery.yaml) +* Added py.typed file into the package root folder and included it setup.cfg as package_data + +## [0.2.3] - 2022-11-08 + +### Changed + +* sampling.py: sampling adapted, removed unused (and non-preferable) options + +* dependencies: + * upgraded to dictIO >= 0.2.2 (now supporting references and expressions in JSON dicts) + * upgraded to ospx >= 0.2.4 + * changed from pyDOE>=0.3.8 to pyDOE2>=1.3.0 + + +## [0.2.2] - 2022-10-05 + +### Changed + +* dependencies: + * upgraded to ospx >= 0.2.3 + + +## [0.2.1] - 2022-10-01 + +### Changed + +* dependencies: + * upgraded to dictIO >= 0.2.0 + * upgraded to ospx >= 0.2.1 + + +## [0.2.0] - 2022-09-28 + +### Changed + +* Dependencies: + * upgraded to ospx >= 0.2.0 + * upgraded to dictIO >= 0.1.2 + +## [0.1.2] - 2022-08-19 + +### Changed + +* farn.py: + * create_samples(): Removed undocumented return value 'layers'. This was simply wrong. create_samples() is not meant to return anything. + +* subProcess.py: + * Changed level of 'per case' log messages from INFO to DEBUG, to reduce cluttering of log. + +### Added + +* farn CLI (and farn.run_farn() API): + * EXPERIMENTAL FEATURE: Added --batch option. Default is False. The batch option lets farn execute commands in batch mode, i.e. asynchroneous instead of sequential. + +### Fixed + +* sampling.py: + * uniformLhs sampling: Corrected the BoundingBox code for the case where Lhs sampling is requested with only one single parameter varied (i.e. 1-dimensional Lhs) + +* farn.py: + * Additional log file handler for farn gets registered only once. Multiple calls to _configure_additional_logging_handler_exclusively_for_farn() will not create multiple handlers, if the file handler for the log file already exists. + +## [0.1.1] - 2022-05-30 + +### Changed + +* Sphinx documentation: Added Changelogs (for combined documentation) +* updated dependency ospx to version >=0.1.1 + +## [0.1.0] - 2022-05-28 + +### Changed + +* Simplified imports from namespace farn. Example: + * Old (<= v0.0.22): + ~~~py + from farn.farn import run_farn + ~~~ + * New: + ~~~py + from farn import run_farn + ~~~ +* Use new simplified imports from namespace dictIO (using updated version of dictIO package) + +* farn.py + * Renamed following functions: + * run_sampling() -> create_samples() + * generate_samples_for_layer() -> create_samples_in_layer() + * register_cases() -> create_cases() + * generate_case_folder_structure() -> create_case_folders() + * generate_case_lists() -> create_case_list_files() + * _create_param_dict_file_in_case_folders() -> create_param_dict_files() + * _execute_command_set_in_case_folders() -> execute_command_set() + * Introduced Dataclass 'Parameter' + * Removed method add_uservars() in dataclass Case (moved the respective code into create_cases() ) + * run_farn(): Removed the ignore_errors argument + * farnDict '_samples' section -> changed naming of '_names' element to '_case_name', to improve clarity of its meaning + * Smaller refactorings to improve code clarity and testability + +* cli/farn.py + * Removed the -i / --ignore-errors argument + + +## [0.0.22] - 2022-05-09 + +* First public release + +## [0.0.17] - 2022-02-14 + +### Added + +* Added support for Python 3.10 + + +[unreleased]: https://github.com/dnv-opensource/farn/compare/v0.3.8...HEAD +[0.3.8]: https://github.com/dnv-opensource/farn/compare/v0.3.7...v0.3.8 +[0.3.7]: https://github.com/dnv-opensource/farn/compare/v0.3.6...v0.3.7 +[0.3.6]: https://github.com/dnv-opensource/farn/compare/v0.3.5...v0.3.6 +[0.3.5]: https://github.com/dnv-opensource/farn/compare/v0.3.4...v0.3.5 +[0.3.4]: https://github.com/dnv-opensource/farn/compare/v0.3.3...v0.3.4 +[0.3.3]: https://github.com/dnv-opensource/farn/compare/v0.3.2...v0.3.3 +[0.3.2]: https://github.com/dnv-opensource/farn/compare/v0.3.1...v0.3.2 +[0.3.1]: https://github.com/dnv-opensource/farn/compare/v0.3.0...v0.3.1 +[0.3.0]: https://github.com/dnv-opensource/farn/compare/v0.2.7...v0.3.0 +[0.2.7]: https://github.com/dnv-opensource/farn/compare/v0.2.6...v0.2.7 +[0.2.6]: https://github.com/dnv-opensource/farn/compare/v0.2.5...v0.2.6 +[0.2.5]: https://github.com/dnv-opensource/farn/compare/v0.2.4...v0.2.5 +[0.2.4]: https://github.com/dnv-opensource/farn/compare/v0.2.3...v0.2.4 +[0.2.3]: https://github.com/dnv-opensource/farn/compare/v0.2.2...v0.2.3 +[0.2.2]: https://github.com/dnv-opensource/farn/compare/v0.2.1...v0.2.2 +[0.2.1]: https://github.com/dnv-opensource/farn/compare/v0.2.0...v0.2.1 +[0.2.0]: https://github.com/dnv-opensource/farn/compare/v0.1.2...v0.2.0 +[0.1.2]: https://github.com/dnv-opensource/farn/compare/v0.1.1...v0.1.2 +[0.1.1]: https://github.com/dnv-opensource/farn/compare/v0.1.0...v0.1.1 +[0.1.0]: https://github.com/dnv-opensource/farn/compare/v0.0.22...v0.1.0 +[0.0.22]: https://github.com/dnv-opensource/farn/compare/v0.0.17...v0.0.22 +[0.0.17]: https://github.com/dnv-opensource/farn/releases/tag/v0.0.17 +[farn]: https://github.com/dnv-opensource/farn + + +[dictIO_docs]: https://dnv-opensource.github.io/dictIO/README.html diff --git a/_sources/CHANGELOG_ospx.md.txt b/_sources/CHANGELOG_ospx.md.txt new file mode 100644 index 00000000..4d122994 --- /dev/null +++ b/_sources/CHANGELOG_ospx.md.txt @@ -0,0 +1,466 @@ +# ospx + +All notable changes to the [ospx] project will be documented in this file.
+The changelog format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +## [Unreleased] + +-/- + + +## [0.3.0] - 2024-11-11 + +### Breaking changes +* The code has been adapted to [dictIO][dictIO_docs] 0.4.0
+ [dictIO][dictIO_docs] 0.4.0 introduced some breaking changes. With the current release 0.3.0 of ospx, the code base has been adapted to these in changes.
+ The most prominent change being that class `dictIO.CppDict` has been replaced by class `dictIO.SDict`. + +### Changed +* Changed from `pip`/`tox` to `uv` as package manager +* README.md : Completely rewrote section "Development Setup", introducing `uv` as package manager. +* Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI +* Updated copyright statement +* VS Code settings: Turned off automatic venv activation +* Replaced black formatter with ruff formatter + +### Solved +* Sphinx documentation: Resolved issue that documentation of class members was generated twice. + +### Added +* Sphinx documentation: Added extension to support Markdown-based diagrams created with Mermaid. +* Added `mypy` as static type checker (in addition to `pyright`) + +### GitHub workflows +* (all workflows): Adapted to use `uv` as package manager +* _test_future.yml : updated Python version to 3.13.0-alpha - 3.13.0 +* _test_future.yml : updated name of test job to 'test313' + +### Dependencies +* Updated to dictIO>=0.4.0 (from dictIO>=0.3.4) +* Updated to ruff>=0.6.3 (from ruff==0.4.2) +* Updated to pyright>=1.1.378 (from pyright==1.1.360) +* Updated to sourcery>=1.22 (from sourcery==1.16) +* Updated to pytest>=8.3 (from pytest>=8.2) +* Updated to Sphinx>=8.0 (from Sphinx>=7.3) +* Updated to sphinx-argparse-cli>=1.17 (from sphinx-argparse-cli>=1.16) +* Updated to myst-parser>=4.0 (from myst-parser>=3.0) +* Updated to furo>=2024.8 (from furo>=2024.5) +* updated to setup-python@v5 (from setup-python@v4) +* updated to actions-gh-pages@v4 (from actions-gh-pages@v3) +* updated to upload-artifact@v4 (from upload-artifact@v3) +* Updated to download-artifact@v4 (from download-artifact@v3) +* updated to checkout@v4 (from checkout@v3) + + +## [0.2.14] - 2024-05-22 + +### Dependencies +* updated to ruff==0.4.2 (from ruff==0.2.1) +* updated to pyright==1.1.360 (from pyright==1.1.350) +* updated to sourcery==1.16 (from sourcery==1.15) +* updated to lxml>=5.2 (from lxml>=5.1) +* updated to types-lxml>=2024.4 (from types-lxml>=5.1) +* updated to pytest>=8.2 (from pytest>=7.4) +* updated to pytest-cov>=5.0 (from pytest-cov>=4.1) +* updated to Sphinx>=7.3 (from Sphinx>=7.2) +* updated to sphinx-argparse-cli>=1.15 (from sphinx-argparse-cli>=1.11) +* updated to myst-parser>=3.0 (from myst-parser>=2.0) +* updated to furo>=2024.4 (from furo>=2023.9.10) +* updated to numpy>=1.26,<2.0 (from numpy>=1.26) +* updated to matplotlib>=3.9 (from matplotlib>=3.8) +* updated to dictIO>=0.3.4 (from dictIO>=0.3.1) +* removed black + +### Changed +* replaced black formatter with ruff formatter +* Changed publishing workflow to use OpenID Connect (Trusted Publisher Management) when publishing to PyPI +* Updated copyright statement +* VS Code settings: Turned off automatic venv activation + + +## [0.2.13] - 2024-02-21 + +### Added +* README.md : Under `Development Setup`, added a step to install current package in "editable" mode, using the pip install -e option. +This removes the need to manually add /src to the PythonPath environment variable in order for debugging and tests to work. + +### Removed +* VS Code settings: Removed the setting which added the /src folder to PythonPath. This is no longer necessary. Installing the project itself as a package in "editable" mode, using the pip install -e option, solves the issue and removes the need to manually add /src to the PythonPath environment variable. + +### Changed +* Moved all project configuration from setup.cfg to pyproject.toml +* Moved all tox configuration from setup.cfg to tox.ini. +* Moved pytest configuration from pyproject.toml to pytest.ini +* Deleted setup.cfg + +### Dependencies +* updated to black[jupyter]==24.1 (from black[jupyter]==23.12) +* updated to version: '==24.1' (from version: '==23.12') +* updated to ruff==0.2.1 (from ruff==0.1.8) +* updated to pyright==1.1.350 (from pyright==1.1.338) +* updated to sourcery==1.15 (from sourcery==1.14) +* updated to lxml>=5.1 (from lxml>=4.9) +* updated to pandas>=2.2 (from pandas>=2.1) + + +## [0.2.12] - 2024-01-09 + +Maintenance Release + +### Dependencies + +* Updated to dictIO>=0.3.1 (from dictIO>=0.2.9) +* Updated other dependencies to latest versions + + +## [0.2.11] - 2023-09-25 + +### Dependencies + +* Updated dependencies to latest versions + + +## [0.2.10] - 2023-06-22 + +### Changed + +* Modularized GitHub workflows +* Changed default Python version in GitHub workflows from 3.10 to 3.11 + +### Dependencies + +* updated to dictIO>=0.2.8 +* requirements-dev.txt: Updated dependencies to latest versions + + +## [0.2.9] - 2023-05-04 + +### Changed + +* dependencies: updated dependencies to latest versions + + +## [0.2.8] - 2023-01-11 + +### Changed + +* Added missing DocStrings for public classes, methods and functions +* Changed links to package documentation to open README.html, not the default index page +* data classes: changed initialisation of mutable types to use default_factory +* ruff: added rule-set "B" (flake8-bugbear) + +### Dependencies + +* updated to dictIO>=0.2.6 + + +## [0.2.7] - 2023-01-04 + +### Changed + +* Linter: Migrated from flake8 to ruff.
+ (Added ruff; removed flake8 and isort) +* Adjusted GitHub CI workflow accordingly.
+ (Added ruff job; removed flake8 and isort jobs) +* VS Code settings: Adjusted Pylance configuration + +### Added + +* Added a batch file 'qa.bat' in root folder to ease local execution of code quality checks + +### Dependencies + +* updated to dictIO>=0.2.5 + + +## [0.2.6] - 2022-12-12 + +### Changed + +* Moved dev-only dependencies from requirements.txt to requirements-dev.txt +* ospx/`__init__`.py and ospx/fmi/`__init__`.py : ensured that imported symbols get also exported
+ (added "as" clause -> "from x import y as y" instead of only "from x import y") +* Configured code quality tools flake8, black, isort, pyright +* Improved code quality, resolving all warnings and errors flagged by the configured code quality tools + (flake8, black, isort, pyright, sourcery) + +### Added + +* Added GitHub workflow 'main.yml' for continuous integration (runs all CI tasks except Sphinx) + * format checks: black, isort + * lint check: flake8, flake8-bugbear + * type check: pyright + * test: uses tox to run pytest on {Windows, Linux, MacOS} with {py39, py310} + * publish: publishing to PyPI (runs only on push of new tag vx.x.x, and after all other jobs succeeded) + * merge_to_release_branch: merge tagged commit to release branch (runs after publish) + +### Dependencies + +* updated to dictIO>=0.2.4 + + +## [0.2.5] - 2022-12-01 + +### Changed + +* variable.py: get_fmi_data_type(): + * Removed the elif branch 'isinstance(arg, Sequence)'.
+ It caused problems as it falsely returned the FMI type 'Enumeration' also for strings.
+ The respective elif branch is for the time being commented out.
+ However, a proper solution is needed as soon as xs:enumeration is used in an OSP case.
+ The problem is registered as [Issue #5](https://github.com/dnv-opensource/ospx/issues/5) +* Code formatting: Changed from yapf to black +* STYLEGUIDE.md : Adjusted to match black formatting +* VS Code settings: Updated to use black as formatter +* requirements.txt: Updated dependencies to their most recent versions +* GitHub actions (yml files): Updated following actions to their most recent versions: + * checkout@v1 -> checkout@v3 + * setup-python@v2 -> setup-python@v4 + * cache@v2 -> cache@v3 + +### Added + +* watchCosim: Added commandline option --scale
+ (allows to scale the generated images by a factor) +* Added sourcery configuration (.sourcery.yaml) +* Added py.typed file into the package root folder and included it setup.cfg as package_data + + +## [0.2.4] - 2022-11-08 + +### Changed + +* Renamed module systemStructure.py to system.py
+ Accordingly, renamed also class SystemStructure to System. + +* Renamed some attributes in FMU class + +* dependencies: + * upgraded to dictIO >= 0.2.2 (now supporting references and expressions in JSON dicts) + +### Added + +* \tests: Added spring_mass_damper example + +* \tests: Added test_fmu.py + +### Solved + +* watchCosim.py : Added try-except statements to catch TypeErrors and ValueErrors when trying to plot non-numerical variables (i.e. String or None) + + + +## [0.2.3] - 2022-10-05 + +### Solved + +* Importer:
+ * Corrected a bug in OspSystemStructureImporter, where multiple connections between two components would not be imported (but only the last one survived). Now, also more than one connection in between two components are imported correctly. + * OspSystemStructureImporter now resolves the type of initial values. I.e. If an initial value in OspSystemStructure is denoted as literal '1' but with Type 'Real', then this initial value will be imported not as integer 1 but as float 1.0 + + +## [0.2.2] - 2022-10-05 + +### Solved + +* Connection:
+ Corrected a bug in Connection.is_variable_connection() and Connection.is_variable_group_connection() which led to Variable Connections not being resolved. + + +## [0.2.1] - 2022-10-01 + +### Changed + +* OspSimulationCase:
+ Changed setup(): FMU files get no longer copied into the case folder by default but stay where they are (i.e. in the library).
+ Only if an FMU is not reachable by a relative path from the case folder, the FMU will get copied into the case folder. + + +* dependencies: + * upgraded to dictIO >= 0.2.0 + + +## [0.2.0] - 2022-09-28 + +### Solved + +* importer.py:
+ Relative paths to libSource and FMUs are now properly resolved, relative to the target directory the OSPSystemStructure.xml is imported into (= folder in which the caseDict is created). + For libSource, by default the absolute path will be entered. This makes the caseDict insensitive when moved or copied into other (case) folders. + +### Changed + +* OSPModelDescription.xml:
+ The handling of OSPModelDescription.xml files has changed: + * no OSPModelDescription.xml files get written by default + * existing OSPModelDescription.xml files will be kept + +* dependencies: + * upgraded to dictIO >= 0.1.2 + +### Added + +* OSPSystemStructure.xml: + * Added support for VariableGroups and VariableGroupConnections (as defined in OSP-IS).
+ importSystemStructure is now also able to import OSPSystemStructure.xml files that use Connections of OSP-IS type 'VariableGroupConnection'. + + * Added support for stepSize attribute:
+ If a \ element in OSPSystemStructure.xml explicitely defines the stepSize attribute, and if the value given for a \'s stepSize inside OSPSystemStructure.xml differs from the default stepSize defined in the FMU's ModelDescription.xml, then the stepSize defined in OSPSystemStructure.xml prevails and will also explicitely be included in the OSPSystemStructure.xml file written by ospCaseBuilder. + + + +## [0.1.2] - 2022-08-19 + +### Changed + +* variable.py: + * variable.start -> added type casting to setter property ensuring an already defined data_type of the variable is not altered when a new start value is set. + +* watchCosim.py + * put watchCosim in working state after time stepping, before changing over to individual data frames + * move *.csv files finally into folder /results + +* Protect png's in result folder from being deleted + +* ospCaseBuilder CLI: + * inspect mode (--inspect) now adds to the results the attributes of the DefaultExperiment element from the FMU's modelDescription.xml + +* plotting.py: + * added further exceptions for non-word characters in title strings + +* dependencies: + * ospx now uses dictIO v0.1.1 + +## [0.1.1] - 2022-05-30 + +### Changed + +* case dict file format: Removed 'root' element from '_environment' section, as it is obsolete. + +### Fixed + +* relative paths in the 'fmu' element led to a FileNotFound error. This is fixed now. + +## [0.1.0] - 2022-05-28 + +### Changed + +* Major refactoring, introducing classes for the main elements such as FMU, Component, SystemStructure etc. +* Simplified imports from namespace ospx. Example: + * Old (<= v0.0.22): + ~~~py + from ospx.ospCaseBuilder import OspCaseBuilder + ~~~ + * New: + ~~~py + from ospx import OspCaseBuilder + ~~~ +* Use new simplified imports from namespace dictIO (using updated version of dictIO package) +* Two changes were introduced in the case dict file format: + 1. Connector element: key 'reference' changed to 'variable':
+ * Old (<= v0.0.22): + ~~~cpp + connectors + { + difference_input_minuend + { + reference difference.IN1; + type input; + } + ~~~ + * New: + ~~~cpp + connectors + { + difference_input_minuend + { + variable difference.IN1; + type input; + } + ~~~ + 2. Connection element: source and target changed from single strings to fully qualified endpoints, providing not only the connector but also the component the connector or variable belongs to: + * Old (<= v0.0.22): + ~~~cpp + connections + { + minuend_to_difference + { + source minuend_output; + target difference_input_minuend; + } + ~~~ + * New: + ~~~cpp + connections + { + minuend_to_difference + { + source + { + component minuend; + connector minuend_output; + } + target + { + component difference; + connector difference_input_minuend; + } + } + ~~~ + * Instead of connector, alternatively also a variable can be referenced in source / target endpoint. Example: + ~~~cpp + connections + { + minuend_to_difference + { + source + { + component minuend; + variable constVal.OUT; + } + target + { + component difference; + variable difference.IN1; + } + } + ~~~ + + +## [0.0.22] - 2022-05-09 + +* First public release + +## [0.0.17] - 2022-02-14 + +### Added + +* Added support for Python 3.10 + + +[unreleased]: https://github.com/dnv-opensource/ospx/compare/v0.2.15...HEAD +[0.2.15]: https://github.com/dnv-opensource/ospx/compare/v0.2.14...v0.2.15 +[0.2.14]: https://github.com/dnv-opensource/ospx/compare/v0.2.13...v0.2.14 +[0.2.13]: https://github.com/dnv-opensource/ospx/compare/v0.2.12...v0.2.13 +[0.2.12]: https://github.com/dnv-opensource/ospx/compare/v0.2.11...v0.2.12 +[0.2.11]: https://github.com/dnv-opensource/ospx/compare/v0.2.10...v0.2.11 +[0.2.10]: https://github.com/dnv-opensource/ospx/compare/v0.2.9...v0.2.10 +[0.2.9]: https://github.com/dnv-opensource/ospx/compare/v0.2.8...v0.2.9 +[0.2.8]: https://github.com/dnv-opensource/ospx/compare/v0.2.7...v0.2.8 +[0.2.7]: https://github.com/dnv-opensource/ospx/compare/v0.2.6...v0.2.7 +[0.2.6]: https://github.com/dnv-opensource/ospx/compare/v0.2.5...v0.2.6 +[0.2.5]: https://github.com/dnv-opensource/ospx/compare/v0.2.4...v0.2.5 +[0.2.4]: https://github.com/dnv-opensource/ospx/compare/v0.2.3...v0.2.4 +[0.2.3]: https://github.com/dnv-opensource/ospx/compare/v0.2.2...v0.2.3 +[0.2.2]: https://github.com/dnv-opensource/ospx/compare/v0.2.1...v0.2.2 +[0.2.1]: https://github.com/dnv-opensource/ospx/compare/v0.2.0...v0.2.1 +[0.2.0]: https://github.com/dnv-opensource/ospx/compare/v0.1.1...v0.2.0 +[0.1.2]: https://github.com/dnv-opensource/ospx/compare/v0.1.1...v0.1.2 +[0.1.1]: https://github.com/dnv-opensource/ospx/compare/v0.1.0...v0.1.1 +[0.1.0]: https://github.com/dnv-opensource/ospx/compare/v0.0.22...v0.1.0 +[0.0.22]: https://github.com/dnv-opensource/ospx/compare/v0.0.17...v0.0.22 +[0.0.17]: https://github.com/dnv-opensource/ospx/releases/tag/v0.0.17 +[ospx]: https://github.com/dnv-opensource/ospx + + +[dictIO_docs]: https://dnv-opensource.github.io/dictIO/README.html diff --git a/_sources/LICENSE.md.txt b/_sources/LICENSE.md.txt new file mode 100644 index 00000000..78f2a431 --- /dev/null +++ b/_sources/LICENSE.md.txt @@ -0,0 +1,3 @@ +# LICENSE +```{include} ../../LICENSE +``` \ No newline at end of file diff --git a/_sources/README.md.txt b/_sources/README.md.txt new file mode 100644 index 00000000..16c6b768 --- /dev/null +++ b/_sources/README.md.txt @@ -0,0 +1,2 @@ +```{include} ../../README.md +``` \ No newline at end of file diff --git a/_sources/README_dictIO.md.txt b/_sources/README_dictIO.md.txt new file mode 100644 index 00000000..4202262f --- /dev/null +++ b/_sources/README_dictIO.md.txt @@ -0,0 +1,202 @@ +[![pypi](https://img.shields.io/pypi/v/dictIO.svg?color=blue)](https://pypi.python.org/pypi/dictIO) +[![versions](https://img.shields.io/pypi/pyversions/dictIO.svg?color=blue)](https://pypi.python.org/pypi/dictIO) +[![license](https://img.shields.io/pypi/l/dictIO.svg)](https://github.com/dnv-opensource/dictIO/blob/main/LICENSE) +![ci](https://img.shields.io/github/actions/workflow/status/dnv-opensource/dictIO/.github%2Fworkflows%2Fnightly_build.yml?label=ci) +[![docs](https://img.shields.io/github/actions/workflow/status/dnv-opensource/dictIO/.github%2Fworkflows%2Fpush_to_release.yml?label=docs)][dictIO_docs] + +# dictIO +dictIO is a Python package to read, write and manipulate dictionary text files. + +It was designed to leverage the versatility of text based dictionary files, or 'dict files' in short, while easing their use in Python through seamless support for Python dicts. + +dictIO supports +* reading and writing Python dicts in dict files. +* usage of references and expressions in dict files, dynamically resolved during reading. +* usage of cascaded dict files, allowing separation of a case-agnostic configuration dict and its case-specific parameterization: baseDict + paramDict = caseDict + +Further, dictIO +* is widely tolerant in reading different flavours (quotes, preserving comments, etc.) +* can read and write also JSON, XML and OpenFOAM (with some limitations) + +## Installation + +```sh +pip install dictIO +``` + +## Usage Example + +dictIO's core class is `SDict`, a generic data structure for serializable dictionaries.
+`SDict` inherits from Python's builtin `dict`. It can hence be used transparently in any context where a `dict` or any other `MutableMapping` type is expected. + +You can use `SDict` the same way you use `dict`. E.g. you can pass a dict literal to its constructor: +```py +from dictIO import SDict + +my_dict: SDict[str, int] = SDict( + { + "foo": 1, + "bar": 2, + } +) +``` + +The simplest way to to dump and load a dict to / from a file, is to use SDict's `dump()` and `load()` instance methods: + +To dump `my_dict` to a file, use `.dump()`: +```py +my_dict.dump("myDict") +``` + +To load the formerly dumped file into a new dict, use `.load()`: +```py +my_dict_loaded: SDict[str, int] = SDict().load("myDict") +``` + +In cases where you need more control over how dict files are read and written,
+dictIO's `DictReader` and `DictWriter` classes offer this flexibility, while still maintaining a simple and high level API: +```py +from dictIO import DictReader, DictWriter + +my_dict = DictReader.read('myDict') +DictWriter.write(my_dict, 'parsed.myDict') +``` + +The above example reads a dict file, merges any (sub-)dicts included through #include directives, evaluates expressions contained in the dict, +and finally saves the read and evaluated dict with prefix 'parsed' as 'parsed.myDict'. + +This sequence of reading, evaluating and writing a dict is also called 'parsing' in dictIO. +Because this task is so common, dictIO provides a convenience class for it: +Using `DictParser.parse()` the above task can be accomplished in one line of code: +```py +from dictIO import DictParser + +DictParser.parse('myDict') +``` + +The `parse` operation can also be executed from the command line, using the 'dictParser' command line script installed with dictIO: +```sh +dictParser myDict +``` + +_For more examples and usage, please refer to dictIO's [documentation][dictIO_docs]._ + + +## File Format +The native file format used by dictIO shares, by intention, some commonalities with the [OpenFOAM](https://www.openfoam.com/documentation/guides/latest/doc/openfoam-guide-input-types.html) file format, but is kept simpler and more tolerant to different flavours of string formatting. + +With some limitations, dictIO supports also reading from and writing to [OpenFOAM](https://www.openfoam.com/documentation/guides/latest/doc/openfoam-guide-input-types.html), [Json](https://www.json.org/json-en.html) and [XML](https://www.w3.org/XML/). + +_For a detailed documentation of the native file format used by dictIO, see [File Format](fileFormat.rst) in [dictIO's documentation][dictIO_docs] on GitHub Pages._ + +## Development Setup + +### 1. Install uv +This project uses `uv` as package manager. +If you haven't already, install [uv](https://docs.astral.sh/uv), preferably using it's ["Standalone installer"](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2) method:
+..on Windows: +```sh +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` +..on MacOS and Linux: +```sh +curl -LsSf https://astral.sh/uv/install.sh | sh +``` +(see [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) for all / alternative installation methods.) + +Once installed, you can update `uv` to its latest version, anytime, by running: +```sh +uv self update +``` + +### 2. Install Python +This project requires Python 3.10 or later.
+If you don't already have a compatible version installed on your machine, the probably most comfortable way to install Python is through `uv`: +```sh +uv python install +``` +This will install the latest stable version of Python into the uv Python directory, i.e. as a uv-managed version of Python. + +Alternatively, and if you want a standalone version of Python on your machine, you can install Python either via `winget`: +```sh +winget install --id Python.Python +``` +or you can download and install Python from the [python.org](https://www.python.org/downloads/) website. + +### 3. Clone the repository +Clone the dictIO repository into your local development directory: +```sh +git clone https://github.com/dnv-opensource/dictIO path/to/your/dev/dictIO +``` + +### 4. Install dependencies +Run `uv sync` to create a virtual environment and install all project dependencies into it: +```sh +uv sync +``` + +### 5. (Optional) Activate the virtual environment +When using `uv`, there is in almost all cases no longer a need to manually activate the virtual environment.
+`uv` will find the `.venv` virtual environment in the working directory or any parent directory, and activate it on the fly whenever you run a command via `uv` inside your project folder structure: +```sh +uv run +``` + +However, you still _can_ manually activate the virtual environment if needed. +When developing in an IDE, for instance, this can in some cases be necessary depending on your IDE settings. +To manually activate the virtual environment, run one of the "known" legacy commands:
+..on Windows: +```sh +.venv\Scripts\activate.bat +``` +..on Linux: +```sh +source .venv/bin/activate +``` + +### 6. Install pre-commit hooks +The `.pre-commit-config.yaml` file in the project root directory contains a configuration for pre-commit hooks. +To install the pre-commit hooks defined therein in your local git repository, run: +```sh +uv run pre-commit install +``` + +All pre-commit hooks configured in `.pre-commit-config.yaml` will now run each time you commit changes. + + +### 7. Test that the installation works +To test that the installation works, run pytest in the project root folder: +```sh +uv run pytest +``` + +## Meta + +Copyright (c) 2024 [DNV](https://www.dnv.com) SE. All rights reserved. + +Frank Lumpitzsch - [@LinkedIn](https://www.linkedin.com/in/frank-lumpitzsch-23013196/) - frank.lumpitzsch@dnv.com + +Claas Rostock - [@LinkedIn](https://www.linkedin.com/in/claasrostock/?locale=en_US) - claas.rostock@dnv.com + +Seunghyeon Yoo - [@LinkedIn](https://www.linkedin.com/in/seunghyeon-yoo-3625173b/) - seunghyeon.yoo@dnv.com + +Distributed under the MIT license. See [LICENSE](LICENSE.md) for more information. + +[https://github.com/dnv-opensource/dictIO](https://github.com/dnv-opensource/dictIO) + +## Contributing + +1. Fork it () +2. Create an issue in your GitHub repo +3. Create your branch based on the issue number and type (`git checkout -b issue-name`) +4. Evaluate and stage the changes you want to commit (`git add -i`) +5. Commit your changes (`git commit -am 'place a descriptive commit message here'`) +6. Push to the branch (`git push origin issue-name`) +7. Create a new Pull Request in GitHub + +For your contribution, please make sure you follow the [STYLEGUIDE](STYLEGUIDE.md) before creating the Pull Request. + + +[dictIO_docs]: https://dnv-opensource.github.io/dictIO/README.html +[ospx_docs]: https://dnv-opensource.github.io/ospx/README.html +[farn_docs]: https://dnv-opensource.github.io/farn/README.html diff --git a/_sources/README_farn.md.txt b/_sources/README_farn.md.txt new file mode 100644 index 00000000..0370779a --- /dev/null +++ b/_sources/README_farn.md.txt @@ -0,0 +1,200 @@ +[![pypi](https://img.shields.io/pypi/v/farn.svg?color=blue)](https://pypi.python.org/pypi/farn) +[![versions](https://img.shields.io/pypi/pyversions/farn.svg?color=blue)](https://pypi.python.org/pypi/farn) +[![license](https://img.shields.io/pypi/l/farn.svg)](https://github.com/dnv-opensource/farn/blob/main/LICENSE) +![ci](https://img.shields.io/github/actions/workflow/status/dnv-opensource/farn/.github%2Fworkflows%2Fnightly_build.yml?label=ci) +[![docs](https://img.shields.io/github/actions/workflow/status/dnv-opensource/farn/.github%2Fworkflows%2Fpush_to_release.yml?label=docs)][farn_docs] + +# farn +[farn][farn_docs] is an n-dimensional case generator. + +Its primary design goal is to parameterize and execute simulation cases. +However, at its core, farn is use-case agnostic and can support a wide spectrum of applications. + +The name ‘farn’ is inspired by the [Barnsley fractal](https://en.wikipedia.org/wiki/Barnsley_fern) + +farn +* runs the sampling of the design space (sampling strategies cover fixed, linSpace, uniformLHS) +* generates the corresponding case folder structure +* copies arbitrary files from a template folder to case folders +* creates case specific parameter files in case folders +* executes user-defined shell command sets in case folders +* builds case specific OSP (co-)simulation files +* runs simulation cases as batch process + +## Installation + +```sh +pip install farn +``` +farn requires the following two (sub-)packages: +1. [dictIO][dictIO_docs]: foundation package, enabling farn to handle configuration files in dictIO dict file format. +2. [ospx][ospx_docs]: extension package, enabling farn to generate OSP (co-)simulation files. + +However, both get installed automatically with farn (just pip install farn and you're done). + +## Usage Example + +farn provides both an API for use inside Python as well as a CLI for shell execution of core functions. + +Reading a farnDict file and creating the corresponding case folder structure: +```py +from farn import run_farn + +run_farn('farnDict', sample=True, generate=True) +``` + +The above task can also be invoked from the command line, using the 'farn' command line script installed with farn: +```sh +farn farnDict --sample --generate +``` + +_For more examples and usage, please refer to [farn's documentation][farn_docs]._ + +Further, the [farn-demo][farn_demo_repo] repository on GitHub is an excellent place for a jumpstart into farn. +Simply clone the [farn-demo][farn_demo_repo] repository to your local machine and click through the demos and related READMEs, by recommendation in the following sequence: + + README in root folder -> guides you through installation of farn + \ospCaseBuilder Demo (see README in ospCaseBuilder folder) + \farn Demo (see README in farn folder) + \importSystemStructure Demo (see README in importSystemStructure folder) + + +## File Format +A farnDict is a file in dictIO dict file format used with farn. + +_For a documentation of the farnDict file format, see [File Format](fileFormat.rst) in [farn's documentation][farn_docs] on GitHub Pages._ + +_For a detailed documentation of the dictIO dict file format used by farn, see [dictIO's documentation][dictIO_docs] on GitHub Pages._ + +## Development Setup + +### 1. Install uv +This project uses `uv` as package manager. +If you haven't already, install [uv](https://docs.astral.sh/uv), preferably using it's ["Standalone installer"](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2) method:
+..on Windows: +```sh +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` +..on MacOS and Linux: +```sh +curl -LsSf https://astral.sh/uv/install.sh | sh +``` +(see [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) for all / alternative installation methods.) + +Once installed, you can update `uv` to its latest version, anytime, by running: +```sh +uv self update +``` + +### 2. Install Python +This project requires Python 3.10 or later.
+If you don't already have a compatible version installed on your machine, the probably most comfortable way to install Python is through `uv`: +```sh +uv python install +``` +This will install the latest stable version of Python into the uv Python directory, i.e. as a uv-managed version of Python. + +Alternatively, and if you want a standalone version of Python on your machine, you can install Python either via `winget`: +```sh +winget install --id Python.Python +``` +or you can download and install Python from the [python.org](https://www.python.org/downloads/) website. + +### 3. Clone the repository +Clone the dictIO repository into your local development directory: +```sh +git clone https://github.com/dnv-opensource/farn path/to/your/dev/farn +``` + +### 4. Install dependencies +Run `uv sync` to create a virtual environment and install all project dependencies into it: +```sh +uv sync +``` + +### 5. (Optional) Install CUDA support +Run `uv sync` with option `--extra cuda` to in addition install torch with CUDA support: +```sh +uv sync --extra cuda +``` + +Alternatively, you can manually install torch with CUDA support. +_Note 1_: Do this preferably _after_ running `uv sync`. That way you ensure a virtual environment exists, which is a prerequisite before you install torch with CUDA support using below `uv pip install` command. + +To manually install torch with CUDA support, generate a `uv pip install` command matching your local machine's operating system using the wizard on the official [PyTorch website](https://pytorch.org/get-started/locally/). +_Note_: As we use `uv` as package manager, remember to replace `pip` in the command generated by the wizard with `uv pip`. + +If you are on Windows, the resulting `uv pip install` command will most likely look something like this: +```sh +uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124 +``` + +_Hint:_ If you are unsure which cuda version to indicate in above `uv pip install .. /cuXXX` command, you can use the shell command `nvidia-smi` on your local system to find out the cuda version supported by the current graphics driver installed on your system. When then generating the `uv pip install` command with the wizard from the [PyTorch website](https://pytorch.org/get-started/locally/), select the cuda version that matches the major version of what your graphics driver supports (major version must match, minor version may deviate). + + +### 6. (Optional) Activate the virtual environment +When using `uv`, there is in almost all cases no longer a need to manually activate the virtual environment.
+`uv` will find the `.venv` virtual environment in the working directory or any parent directory, and activate it on the fly whenever you run a command via `uv` inside your project folder structure: +```sh +uv run +``` + +However, you still _can_ manually activate the virtual environment if needed. +When developing in an IDE, for instance, this can in some cases be necessary depending on your IDE settings. +To manually activate the virtual environment, run one of the "known" legacy commands:
+..on Windows: +```sh +.venv\Scripts\activate.bat +``` +..on Linux: +```sh +source .venv/bin/activate +``` + +### 7. Install pre-commit hooks +The `.pre-commit-config.yaml` file in the project root directory contains a configuration for pre-commit hooks. +To install the pre-commit hooks defined therein in your local git repository, run: +```sh +uv run pre-commit install +``` + +All pre-commit hooks configured in `.pre-commit-config.yaml` will now run each time you commit changes. + + +### 8. Test that the installation works +To test that the installation works, run pytest in the project root folder: +```sh +uv run pytest +``` + +## Meta + +Copyright (c) 2024 [DNV](https://www.dnv.com) SE. All rights reserved. + +Frank Lumpitzsch – [@LinkedIn](https://www.linkedin.com/in/frank-lumpitzsch-23013196/) – frank.lumpitzsch@dnv.com + +Claas Rostock – [@LinkedIn](https://www.linkedin.com/in/claasrostock/?locale=en_US) – claas.rostock@dnv.com + +Seunghyeon Yoo – [@LinkedIn](https://www.linkedin.com/in/seunghyeon-yoo-3625173b/) – seunghyeon.yoo@dnv.com + +Distributed under the MIT license. See [LICENSE](LICENSE.md) for more information. + +[https://github.com/dnv-opensource/farn](https://github.com/dnv-opensource/farn) + +## Contributing + +1. Fork it () +2. Create an issue in your GitHub repo +3. Create your branch based on the issue number and type (`git checkout -b issue-name`) +4. Evaluate and stage the changes you want to commit (`git add -i`) +5. Commit your changes (`git commit -am 'place a descriptive commit message here'`) +6. Push to the branch (`git push origin issue-name`) +7. Create a new Pull Request in GitHub + +For your contribution, please make sure you follow the [STYLEGUIDE](STYLEGUIDE.md) before creating the Pull Request. + + +[dictIO_docs]: https://dnv-opensource.github.io/dictIO/README.html +[ospx_docs]: https://dnv-opensource.github.io/ospx/README.html +[farn_docs]: https://dnv-opensource.github.io/farn/README.html +[farn_demo_repo]: https://github.com/dnv-opensource/farn-demo diff --git a/_sources/README_ospx.md.txt b/_sources/README_ospx.md.txt new file mode 100644 index 00000000..ab23d21b --- /dev/null +++ b/_sources/README_ospx.md.txt @@ -0,0 +1,180 @@ +[![pypi](https://img.shields.io/pypi/v/ospx.svg?color=blue)](https://pypi.python.org/pypi/ospx) +[![versions](https://img.shields.io/pypi/pyversions/ospx.svg?color=blue)](https://pypi.python.org/pypi/ospx) +[![license](https://img.shields.io/pypi/l/ospx.svg)](https://github.com/dnv-opensource/ospx/blob/main/LICENSE) +![ci](https://img.shields.io/github/actions/workflow/status/dnv-opensource/ospx/.github%2Fworkflows%2Fnightly_build.yml?label=ci) +[![docs](https://img.shields.io/github/actions/workflow/status/dnv-opensource/ospx/.github%2Fworkflows%2Fpush_to_release.yml?label=docs)][ospx_docs] + +# ospx +ospx is an extension package to [farn][farn_docs], adding support to build [OSP][osp_docs] (co-)simulation cases using functional mockup units (FMUs). + +ospx supports +* building of case-specific [OSP][osp_docs] (co-)simulation configuration files +* watching the progress of cosim, and saving final simulation results as a pandas dataframe. + +## Installation + +```sh +pip install ospx +``` +ospx requires the following (sub-)package: +* [dictIO][dictIO_docs]: foundation package, enabling ospx to handle configuration files in dictIO dict file format. + +However, dictIO gets installed automatically with ospx. + +## Usage Example + +ospx provides both an API for use inside Python as well as a CLI for shell execution of core functions. + +Reading a caseDict file and building the case-specific OSP (co-)simulation configuration files: +```py +from ospx import OspCaseBuilder + +OspCaseBuilder.build('caseDict') +``` + +The above task can also be invoked from the command line, using the 'ospCaseBuilder' command line script installed with ospx: +```sh +ospCaseBuilder caseDict +``` + +_For more examples and usage, please refer to [ospx's documentation][ospx_docs]._ + +## File Format +A caseDict is a file in dictIO dict file format used with farn. + +_For a documentation of the caseDict file format, see [File Format](fileFormat.rst) in [ospx's documentation][ospx_docs] on GitHub Pages._ + +_For a detailed documentation of the dictIO dict file format used by farn, see [dictIO's documentation][dictIO_docs] on GitHub Pages._ + +## Development Setup + +### 1. Install uv +This project uses `uv` as package manager. +If you haven't already, install [uv](https://docs.astral.sh/uv), preferably using it's ["Standalone installer"](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2) method:
+..on Windows: +```sh +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` +..on MacOS and Linux: +```sh +curl -LsSf https://astral.sh/uv/install.sh | sh +``` +(see [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) for all / alternative installation methods.) + +Once installed, you can update `uv` to its latest version, anytime, by running: +```sh +uv self update +``` + +### 2. Install Python +This project requires Python 3.10 or later.
+If you don't already have a compatible version installed on your machine, the probably most comfortable way to install Python is through `uv`: +```sh +uv python install +``` +This will install the latest stable version of Python into the uv Python directory, i.e. as a uv-managed version of Python. + +Alternatively, and if you want a standalone version of Python on your machine, you can install Python either via `winget`: +```sh +winget install --id Python.Python +``` +or you can download and install Python from the [python.org](https://www.python.org/downloads/) website. + +### 3. Clone the repository +Clone the dictIO repository into your local development directory: +```sh +git clone https://github.com/dnv-opensource/ospx path/to/your/dev/ospx +``` + +### 4. Install dependencies +Run `uv sync` to create a virtual environment and install all project dependencies into it: +```sh +uv sync +``` + +### 5. (Optional) Install CUDA support +Run `uv sync` with option `--extra cuda` to in addition install torch with CUDA support: +```sh +uv sync --extra cuda +``` + +Alternatively, you can manually install torch with CUDA support. +_Note 1_: Do this preferably _after_ running `uv sync`. That way you ensure a virtual environment exists, which is a prerequisite before you install torch with CUDA support using below `uv pip install` command. + +To manually install torch with CUDA support, generate a `uv pip install` command matching your local machine's operating system using the wizard on the official [PyTorch website](https://pytorch.org/get-started/locally/). +_Note_: As we use `uv` as package manager, remember to replace `pip` in the command generated by the wizard with `uv pip`. + +If you are on Windows, the resulting `uv pip install` command will most likely look something like this: +```sh +uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124 +``` + +_Hint:_ If you are unsure which cuda version to indicate in above `uv pip install .. /cuXXX` command, you can use the shell command `nvidia-smi` on your local system to find out the cuda version supported by the current graphics driver installed on your system. When then generating the `uv pip install` command with the wizard from the [PyTorch website](https://pytorch.org/get-started/locally/), select the cuda version that matches the major version of what your graphics driver supports (major version must match, minor version may deviate). + + +### 6. (Optional) Activate the virtual environment +When using `uv`, there is in almost all cases no longer a need to manually activate the virtual environment.
+`uv` will find the `.venv` virtual environment in the working directory or any parent directory, and activate it on the fly whenever you run a command via `uv` inside your project folder structure: +```sh +uv run +``` + +However, you still _can_ manually activate the virtual environment if needed. +When developing in an IDE, for instance, this can in some cases be necessary depending on your IDE settings. +To manually activate the virtual environment, run one of the "known" legacy commands:
+..on Windows: +```sh +.venv\Scripts\activate.bat +``` +..on Linux: +```sh +source .venv/bin/activate +``` + +### 7. Install pre-commit hooks +The `.pre-commit-config.yaml` file in the project root directory contains a configuration for pre-commit hooks. +To install the pre-commit hooks defined therein in your local git repository, run: +```sh +uv run pre-commit install +``` + +All pre-commit hooks configured in `.pre-commit-config.yaml` will now run each time you commit changes. + + +### 8. Test that the installation works +To test that the installation works, run pytest in the project root folder: +```sh +uv run pytest +``` + +## Meta + +Copyright (c) 2024 [DNV](https://www.dnv.com) SE. All rights reserved. + +Frank Lumpitzsch – [@LinkedIn](https://www.linkedin.com/in/frank-lumpitzsch-23013196/) – frank.lumpitzsch@dnv.com + +Claas Rostock – [@LinkedIn](https://www.linkedin.com/in/claasrostock/?locale=en_US) – claas.rostock@dnv.com + +Seunghyeon Yoo – [@LinkedIn](https://www.linkedin.com/in/seunghyeon-yoo-3625173b/) – seunghyeon.yoo@dnv.com + +Distributed under the MIT license. See [LICENSE](LICENSE.md) for more information. + +[https://github.com/dnv-opensource/ospx](https://github.com/dnv-opensource/ospx) + +## Contributing + +1. Fork it () +2. Create an issue in your GitHub repo +3. Create your branch based on the issue number and type (`git checkout -b issue-name`) +4. Evaluate and stage the changes you want to commit (`git add -i`) +5. Commit your changes (`git commit -am 'place a descriptive commit message here'`) +6. Push to the branch (`git push origin issue-name`) +7. Create a new Pull Request in GitHub + +For your contribution, please make sure you follow the [STYLEGUIDE](STYLEGUIDE.md) before creating the Pull Request. + + +[dictIO_docs]: https://dnv-opensource.github.io/dictIO/README.html +[ospx_docs]: https://dnv-opensource.github.io/ospx/README.html +[farn_docs]: https://dnv-opensource.github.io/farn/README.html +[osp_docs]: https://open-simulation-platform.github.io/ diff --git a/_sources/STYLEGUIDE.md.txt b/_sources/STYLEGUIDE.md.txt new file mode 100644 index 00000000..d5ac6e1c --- /dev/null +++ b/_sources/STYLEGUIDE.md.txt @@ -0,0 +1,2 @@ +```{include} ../../STYLEGUIDE.md +``` \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.cpp_dict.CppDict.rst.txt b/_sources/_autosummary/dictIO.cpp_dict.CppDict.rst.txt new file mode 100644 index 00000000..e8406e38 --- /dev/null +++ b/_sources/_autosummary/dictIO.cpp_dict.CppDict.rst.txt @@ -0,0 +1,54 @@ +CppDict +======= + +.. currentmodule:: dictIO.cpp_dict + +.. autoclass:: CppDict + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~CppDict.__init__ + ~CppDict.clear + ~CppDict.copy + ~CppDict.dump + ~CppDict.find_global_key + ~CppDict.fromkeys + ~CppDict.get + ~CppDict.global_key_exists + ~CppDict.include + ~CppDict.items + ~CppDict.keys + ~CppDict.load + ~CppDict.merge + ~CppDict.order_keys + ~CppDict.pop + ~CppDict.popitem + ~CppDict.reduce_scope + ~CppDict.reset + ~CppDict.set_global_key + ~CppDict.setdefault + ~CppDict.update + ~CppDict.values + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~CppDict.data + ~CppDict.name + ~CppDict.path + ~CppDict.source_file + ~CppDict.variables + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.cpp_dict.rst.txt b/_sources/_autosummary/dictIO.cpp_dict.rst.txt new file mode 100644 index 00000000..a861dc95 --- /dev/null +++ b/_sources/_autosummary/dictIO.cpp_dict.rst.txt @@ -0,0 +1,17 @@ +dictIO.cpp\_dict +================ + +.. automodule:: dictIO.cpp_dict + :members: + :exclude-members: CppDict, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + CppDict + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.dict.SDict.rst.txt b/_sources/_autosummary/dictIO.dict.SDict.rst.txt new file mode 100644 index 00000000..1b51e5e9 --- /dev/null +++ b/_sources/_autosummary/dictIO.dict.SDict.rst.txt @@ -0,0 +1,54 @@ +SDict +===== + +.. currentmodule:: dictIO.dict + +.. autoclass:: SDict + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~SDict.__init__ + ~SDict.clear + ~SDict.copy + ~SDict.dump + ~SDict.find_global_key + ~SDict.fromkeys + ~SDict.get + ~SDict.global_key_exists + ~SDict.include + ~SDict.items + ~SDict.keys + ~SDict.load + ~SDict.merge + ~SDict.order_keys + ~SDict.pop + ~SDict.popitem + ~SDict.reduce_scope + ~SDict.reset + ~SDict.set_global_key + ~SDict.setdefault + ~SDict.update + ~SDict.values + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~SDict.data + ~SDict.name + ~SDict.path + ~SDict.source_file + ~SDict.variables + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.dict.rst.txt b/_sources/_autosummary/dictIO.dict.rst.txt new file mode 100644 index 00000000..bf9dbc6e --- /dev/null +++ b/_sources/_autosummary/dictIO.dict.rst.txt @@ -0,0 +1,17 @@ +dictIO.dict +=========== + +.. automodule:: dictIO.dict + :members: + :exclude-members: SDict, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + SDict + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.dict_parser.DictParser.rst.txt b/_sources/_autosummary/dictIO.dict_parser.DictParser.rst.txt new file mode 100644 index 00000000..cd3987f3 --- /dev/null +++ b/_sources/_autosummary/dictIO.dict_parser.DictParser.rst.txt @@ -0,0 +1,25 @@ +DictParser +========== + +.. currentmodule:: dictIO.dict_parser + +.. autoclass:: DictParser + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~DictParser.__init__ + ~DictParser.parse + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.dict_parser.rst.txt b/_sources/_autosummary/dictIO.dict_parser.rst.txt new file mode 100644 index 00000000..c1602954 --- /dev/null +++ b/_sources/_autosummary/dictIO.dict_parser.rst.txt @@ -0,0 +1,17 @@ +dictIO.dict\_parser +=================== + +.. automodule:: dictIO.dict_parser + :members: + :exclude-members: DictParser, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + DictParser + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.dict_reader.DictReader.rst.txt b/_sources/_autosummary/dictIO.dict_reader.DictReader.rst.txt new file mode 100644 index 00000000..cc039c2e --- /dev/null +++ b/_sources/_autosummary/dictIO.dict_reader.DictReader.rst.txt @@ -0,0 +1,25 @@ +DictReader +========== + +.. currentmodule:: dictIO.dict_reader + +.. autoclass:: DictReader + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~DictReader.__init__ + ~DictReader.read + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.dict_reader.rst.txt b/_sources/_autosummary/dictIO.dict_reader.rst.txt new file mode 100644 index 00000000..3ac14d1a --- /dev/null +++ b/_sources/_autosummary/dictIO.dict_reader.rst.txt @@ -0,0 +1,17 @@ +dictIO.dict\_reader +=================== + +.. automodule:: dictIO.dict_reader + :members: + :exclude-members: DictReader, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + DictReader + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.dict_writer.DictWriter.rst.txt b/_sources/_autosummary/dictIO.dict_writer.DictWriter.rst.txt new file mode 100644 index 00000000..dc471ac8 --- /dev/null +++ b/_sources/_autosummary/dictIO.dict_writer.DictWriter.rst.txt @@ -0,0 +1,25 @@ +DictWriter +========== + +.. currentmodule:: dictIO.dict_writer + +.. autoclass:: DictWriter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~DictWriter.__init__ + ~DictWriter.write + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.dict_writer.rst.txt b/_sources/_autosummary/dictIO.dict_writer.rst.txt new file mode 100644 index 00000000..e32cf2bb --- /dev/null +++ b/_sources/_autosummary/dictIO.dict_writer.rst.txt @@ -0,0 +1,22 @@ +dictIO.dict\_writer +=================== + +.. automodule:: dictIO.dict_writer + :members: + :exclude-members: DictWriter, + + + + + .. rubric:: Functions + .. autosummary:: + + create_target_file_name + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + DictWriter + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.formatter.FoamFormatter.rst.txt b/_sources/_autosummary/dictIO.formatter.FoamFormatter.rst.txt new file mode 100644 index 00000000..1ab0d84b --- /dev/null +++ b/_sources/_autosummary/dictIO.formatter.FoamFormatter.rst.txt @@ -0,0 +1,48 @@ +FoamFormatter +============= + +.. currentmodule:: dictIO.formatter + +.. autoclass:: FoamFormatter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~FoamFormatter.__init__ + ~FoamFormatter.add_double_quotes + ~FoamFormatter.add_single_quotes + ~FoamFormatter.format_bool + ~FoamFormatter.format_dict + ~FoamFormatter.format_empty_string + ~FoamFormatter.format_expression_string + ~FoamFormatter.format_float + ~FoamFormatter.format_int + ~FoamFormatter.format_key + ~FoamFormatter.format_multi_word_string + ~FoamFormatter.format_none + ~FoamFormatter.format_reference_string + ~FoamFormatter.format_single_word_string + ~FoamFormatter.format_string + ~FoamFormatter.format_string_with_nested_string + ~FoamFormatter.format_value + ~FoamFormatter.format_values + ~FoamFormatter.get_formatter + ~FoamFormatter.insert_block_comments + ~FoamFormatter.insert_includes + ~FoamFormatter.insert_line_comments + ~FoamFormatter.make_default_block_comment + ~FoamFormatter.remove_trailing_spaces + ~FoamFormatter.to_string + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.formatter.Formatter.rst.txt b/_sources/_autosummary/dictIO.formatter.Formatter.rst.txt new file mode 100644 index 00000000..3a303eeb --- /dev/null +++ b/_sources/_autosummary/dictIO.formatter.Formatter.rst.txt @@ -0,0 +1,42 @@ +Formatter +========= + +.. currentmodule:: dictIO.formatter + +.. autoclass:: Formatter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Formatter.__init__ + ~Formatter.add_double_quotes + ~Formatter.add_single_quotes + ~Formatter.format_bool + ~Formatter.format_empty_string + ~Formatter.format_expression_string + ~Formatter.format_float + ~Formatter.format_int + ~Formatter.format_key + ~Formatter.format_multi_word_string + ~Formatter.format_none + ~Formatter.format_reference_string + ~Formatter.format_single_word_string + ~Formatter.format_string + ~Formatter.format_string_with_nested_string + ~Formatter.format_value + ~Formatter.format_values + ~Formatter.get_formatter + ~Formatter.to_string + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.formatter.JsonFormatter.rst.txt b/_sources/_autosummary/dictIO.formatter.JsonFormatter.rst.txt new file mode 100644 index 00000000..fa2d10b1 --- /dev/null +++ b/_sources/_autosummary/dictIO.formatter.JsonFormatter.rst.txt @@ -0,0 +1,43 @@ +JsonFormatter +============= + +.. currentmodule:: dictIO.formatter + +.. autoclass:: JsonFormatter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~JsonFormatter.__init__ + ~JsonFormatter.add_double_quotes + ~JsonFormatter.add_single_quotes + ~JsonFormatter.format_bool + ~JsonFormatter.format_empty_string + ~JsonFormatter.format_expression_string + ~JsonFormatter.format_float + ~JsonFormatter.format_int + ~JsonFormatter.format_key + ~JsonFormatter.format_multi_word_string + ~JsonFormatter.format_none + ~JsonFormatter.format_reference_string + ~JsonFormatter.format_single_word_string + ~JsonFormatter.format_string + ~JsonFormatter.format_string_with_nested_string + ~JsonFormatter.format_value + ~JsonFormatter.format_values + ~JsonFormatter.get_formatter + ~JsonFormatter.insert_includes + ~JsonFormatter.to_string + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.formatter.NativeFormatter.rst.txt b/_sources/_autosummary/dictIO.formatter.NativeFormatter.rst.txt new file mode 100644 index 00000000..fe6f5727 --- /dev/null +++ b/_sources/_autosummary/dictIO.formatter.NativeFormatter.rst.txt @@ -0,0 +1,48 @@ +NativeFormatter +=============== + +.. currentmodule:: dictIO.formatter + +.. autoclass:: NativeFormatter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~NativeFormatter.__init__ + ~NativeFormatter.add_double_quotes + ~NativeFormatter.add_single_quotes + ~NativeFormatter.format_bool + ~NativeFormatter.format_dict + ~NativeFormatter.format_empty_string + ~NativeFormatter.format_expression_string + ~NativeFormatter.format_float + ~NativeFormatter.format_int + ~NativeFormatter.format_key + ~NativeFormatter.format_multi_word_string + ~NativeFormatter.format_none + ~NativeFormatter.format_reference_string + ~NativeFormatter.format_single_word_string + ~NativeFormatter.format_string + ~NativeFormatter.format_string_with_nested_string + ~NativeFormatter.format_value + ~NativeFormatter.format_values + ~NativeFormatter.get_formatter + ~NativeFormatter.insert_block_comments + ~NativeFormatter.insert_includes + ~NativeFormatter.insert_line_comments + ~NativeFormatter.make_default_block_comment + ~NativeFormatter.remove_trailing_spaces + ~NativeFormatter.to_string + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.formatter.XmlFormatter.rst.txt b/_sources/_autosummary/dictIO.formatter.XmlFormatter.rst.txt new file mode 100644 index 00000000..a79b9cf2 --- /dev/null +++ b/_sources/_autosummary/dictIO.formatter.XmlFormatter.rst.txt @@ -0,0 +1,43 @@ +XmlFormatter +============ + +.. currentmodule:: dictIO.formatter + +.. autoclass:: XmlFormatter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~XmlFormatter.__init__ + ~XmlFormatter.add_double_quotes + ~XmlFormatter.add_single_quotes + ~XmlFormatter.format_bool + ~XmlFormatter.format_empty_string + ~XmlFormatter.format_expression_string + ~XmlFormatter.format_float + ~XmlFormatter.format_int + ~XmlFormatter.format_key + ~XmlFormatter.format_multi_word_string + ~XmlFormatter.format_none + ~XmlFormatter.format_reference_string + ~XmlFormatter.format_single_word_string + ~XmlFormatter.format_string + ~XmlFormatter.format_string_with_nested_string + ~XmlFormatter.format_value + ~XmlFormatter.format_values + ~XmlFormatter.get_formatter + ~XmlFormatter.populate_into_element + ~XmlFormatter.to_string + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.formatter.rst.txt b/_sources/_autosummary/dictIO.formatter.rst.txt new file mode 100644 index 00000000..d818e04a --- /dev/null +++ b/_sources/_autosummary/dictIO.formatter.rst.txt @@ -0,0 +1,21 @@ +dictIO.formatter +================ + +.. automodule:: dictIO.formatter + :members: + :exclude-members: FoamFormatter,Formatter,JsonFormatter,NativeFormatter,XmlFormatter, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + FoamFormatter + Formatter + JsonFormatter + NativeFormatter + XmlFormatter + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.parser.FoamParser.rst.txt b/_sources/_autosummary/dictIO.parser.FoamParser.rst.txt new file mode 100644 index 00000000..6498f0f6 --- /dev/null +++ b/_sources/_autosummary/dictIO.parser.FoamParser.rst.txt @@ -0,0 +1,32 @@ +FoamParser +========== + +.. currentmodule:: dictIO.parser + +.. autoclass:: FoamParser + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~FoamParser.__init__ + ~FoamParser.get_parser + ~FoamParser.parse_file + ~FoamParser.parse_key + ~FoamParser.parse_string + ~FoamParser.parse_value + ~FoamParser.parse_values + ~FoamParser.remove_quotes_from_string + ~FoamParser.remove_quotes_from_strings + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.parser.JsonParser.rst.txt b/_sources/_autosummary/dictIO.parser.JsonParser.rst.txt new file mode 100644 index 00000000..dfac04f5 --- /dev/null +++ b/_sources/_autosummary/dictIO.parser.JsonParser.rst.txt @@ -0,0 +1,32 @@ +JsonParser +========== + +.. currentmodule:: dictIO.parser + +.. autoclass:: JsonParser + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~JsonParser.__init__ + ~JsonParser.get_parser + ~JsonParser.parse_file + ~JsonParser.parse_key + ~JsonParser.parse_string + ~JsonParser.parse_value + ~JsonParser.parse_values + ~JsonParser.remove_quotes_from_string + ~JsonParser.remove_quotes_from_strings + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.parser.NativeParser.rst.txt b/_sources/_autosummary/dictIO.parser.NativeParser.rst.txt new file mode 100644 index 00000000..cadb9dee --- /dev/null +++ b/_sources/_autosummary/dictIO.parser.NativeParser.rst.txt @@ -0,0 +1,32 @@ +NativeParser +============ + +.. currentmodule:: dictIO.parser + +.. autoclass:: NativeParser + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~NativeParser.__init__ + ~NativeParser.get_parser + ~NativeParser.parse_file + ~NativeParser.parse_key + ~NativeParser.parse_string + ~NativeParser.parse_value + ~NativeParser.parse_values + ~NativeParser.remove_quotes_from_string + ~NativeParser.remove_quotes_from_strings + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.parser.Parser.rst.txt b/_sources/_autosummary/dictIO.parser.Parser.rst.txt new file mode 100644 index 00000000..145d0f14 --- /dev/null +++ b/_sources/_autosummary/dictIO.parser.Parser.rst.txt @@ -0,0 +1,32 @@ +Parser +====== + +.. currentmodule:: dictIO.parser + +.. autoclass:: Parser + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Parser.__init__ + ~Parser.get_parser + ~Parser.parse_file + ~Parser.parse_key + ~Parser.parse_string + ~Parser.parse_value + ~Parser.parse_values + ~Parser.remove_quotes_from_string + ~Parser.remove_quotes_from_strings + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.parser.XmlParser.rst.txt b/_sources/_autosummary/dictIO.parser.XmlParser.rst.txt new file mode 100644 index 00000000..26c22eb9 --- /dev/null +++ b/_sources/_autosummary/dictIO.parser.XmlParser.rst.txt @@ -0,0 +1,32 @@ +XmlParser +========= + +.. currentmodule:: dictIO.parser + +.. autoclass:: XmlParser + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~XmlParser.__init__ + ~XmlParser.get_parser + ~XmlParser.parse_file + ~XmlParser.parse_key + ~XmlParser.parse_string + ~XmlParser.parse_value + ~XmlParser.parse_values + ~XmlParser.remove_quotes_from_string + ~XmlParser.remove_quotes_from_strings + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.parser.rst.txt b/_sources/_autosummary/dictIO.parser.rst.txt new file mode 100644 index 00000000..5b96e9fc --- /dev/null +++ b/_sources/_autosummary/dictIO.parser.rst.txt @@ -0,0 +1,21 @@ +dictIO.parser +============= + +.. automodule:: dictIO.parser + :members: + :exclude-members: FoamParser,JsonParser,NativeParser,Parser,XmlParser, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + FoamParser + JsonParser + NativeParser + Parser + XmlParser + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.types.rst.txt b/_sources/_autosummary/dictIO.types.rst.txt new file mode 100644 index 00000000..f63f1464 --- /dev/null +++ b/_sources/_autosummary/dictIO.types.rst.txt @@ -0,0 +1,8 @@ +dictIO.types +============ + +.. automodule:: dictIO.types + :members: + + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.utils.counter.BorgCounter.rst.txt b/_sources/_autosummary/dictIO.utils.counter.BorgCounter.rst.txt new file mode 100644 index 00000000..a689e285 --- /dev/null +++ b/_sources/_autosummary/dictIO.utils.counter.BorgCounter.rst.txt @@ -0,0 +1,30 @@ +BorgCounter +=========== + +.. currentmodule:: dictIO.utils.counter + +.. autoclass:: BorgCounter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~BorgCounter.__init__ + ~BorgCounter.reset + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~BorgCounter.Borg + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.utils.counter.DejaVue.rst.txt b/_sources/_autosummary/dictIO.utils.counter.DejaVue.rst.txt new file mode 100644 index 00000000..14d07180 --- /dev/null +++ b/_sources/_autosummary/dictIO.utils.counter.DejaVue.rst.txt @@ -0,0 +1,31 @@ +DejaVue +======= + +.. currentmodule:: dictIO.utils.counter + +.. autoclass:: DejaVue + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~DejaVue.__init__ + ~DejaVue.reset + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~DejaVue.djv + ~DejaVue.strings + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.utils.counter.Indenter.rst.txt b/_sources/_autosummary/dictIO.utils.counter.Indenter.rst.txt new file mode 100644 index 00000000..fd6954b2 --- /dev/null +++ b/_sources/_autosummary/dictIO.utils.counter.Indenter.rst.txt @@ -0,0 +1,32 @@ +Indenter +======== + +.. currentmodule:: dictIO.utils.counter + +.. autoclass:: Indenter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Indenter.__init__ + ~Indenter.decr + ~Indenter.incr + ~Indenter.reset + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Indenter.Ind + + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.utils.counter.rst.txt b/_sources/_autosummary/dictIO.utils.counter.rst.txt new file mode 100644 index 00000000..0e52ef86 --- /dev/null +++ b/_sources/_autosummary/dictIO.utils.counter.rst.txt @@ -0,0 +1,19 @@ +dictIO.utils.counter +==================== + +.. automodule:: dictIO.utils.counter + :members: + :exclude-members: BorgCounter,DejaVue,Indenter, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + BorgCounter + DejaVue + Indenter + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.utils.dict.rst.txt b/_sources/_autosummary/dictIO.utils.dict.rst.txt new file mode 100644 index 00000000..2c4b8eb9 --- /dev/null +++ b/_sources/_autosummary/dictIO.utils.dict.rst.txt @@ -0,0 +1,16 @@ +dictIO.utils.dict +================= + +.. automodule:: dictIO.utils.dict + :members: + + + + .. rubric:: Functions + .. autosummary:: + + find_global_key + global_key_exists + order_keys + set_global_key + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.utils.logging.rst.txt b/_sources/_autosummary/dictIO.utils.logging.rst.txt new file mode 100644 index 00000000..b5015767 --- /dev/null +++ b/_sources/_autosummary/dictIO.utils.logging.rst.txt @@ -0,0 +1,13 @@ +dictIO.utils.logging +==================== + +.. automodule:: dictIO.utils.logging + :members: + + + + .. rubric:: Functions + .. autosummary:: + + configure_logging + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.utils.path.rst.txt b/_sources/_autosummary/dictIO.utils.path.rst.txt new file mode 100644 index 00000000..bc4da2ce --- /dev/null +++ b/_sources/_autosummary/dictIO.utils.path.rst.txt @@ -0,0 +1,14 @@ +dictIO.utils.path +================= + +.. automodule:: dictIO.utils.path + :members: + + + + .. rubric:: Functions + .. autosummary:: + + highest_common_root_folder + relative_path + \ No newline at end of file diff --git a/_sources/_autosummary/dictIO.utils.rst.txt b/_sources/_autosummary/dictIO.utils.rst.txt new file mode 100644 index 00000000..c4c9105d --- /dev/null +++ b/_sources/_autosummary/dictIO.utils.rst.txt @@ -0,0 +1,19 @@ +dictIO.utils +============ + +.. automodule:: dictIO.utils + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + counter + dict + logging + path + strings diff --git a/_sources/_autosummary/dictIO.utils.strings.rst.txt b/_sources/_autosummary/dictIO.utils.strings.rst.txt new file mode 100644 index 00000000..a9e886ad --- /dev/null +++ b/_sources/_autosummary/dictIO.utils.strings.rst.txt @@ -0,0 +1,14 @@ +dictIO.utils.strings +==================== + +.. automodule:: dictIO.utils.strings + :members: + + + + .. rubric:: Functions + .. autosummary:: + + remove_quotes + string_diff + \ No newline at end of file diff --git a/_sources/_autosummary/farn.core.case.Case.rst.txt b/_sources/_autosummary/farn.core.case.Case.rst.txt new file mode 100644 index 00000000..b6e818d6 --- /dev/null +++ b/_sources/_autosummary/farn.core.case.Case.rst.txt @@ -0,0 +1,31 @@ +Case +==== + +.. currentmodule:: farn.core.case + +.. autoclass:: Case + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Case.__init__ + ~Case.add_parameters + ~Case.to_dict + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Case.is_valid + + \ No newline at end of file diff --git a/_sources/_autosummary/farn.core.case.CaseStatus.rst.txt b/_sources/_autosummary/farn.core.case.CaseStatus.rst.txt new file mode 100644 index 00000000..f5d6e1bc --- /dev/null +++ b/_sources/_autosummary/farn.core.case.CaseStatus.rst.txt @@ -0,0 +1,44 @@ +CaseStatus +========== + +.. currentmodule:: farn.core.case + +.. autoclass:: CaseStatus + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~CaseStatus.conjugate + ~CaseStatus.bit_length + ~CaseStatus.bit_count + ~CaseStatus.to_bytes + ~CaseStatus.from_bytes + ~CaseStatus.as_integer_ratio + ~CaseStatus.is_integer + ~CaseStatus.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~CaseStatus.real + ~CaseStatus.imag + ~CaseStatus.numerator + ~CaseStatus.denominator + ~CaseStatus.NONE + ~CaseStatus.FAILURE + ~CaseStatus.PREPARED + ~CaseStatus.RUNNING + ~CaseStatus.SUCCESS + + \ No newline at end of file diff --git a/_sources/_autosummary/farn.core.case.Cases.rst.txt b/_sources/_autosummary/farn.core.case.Cases.rst.txt new file mode 100644 index 00000000..584db2fa --- /dev/null +++ b/_sources/_autosummary/farn.core.case.Cases.rst.txt @@ -0,0 +1,39 @@ +Cases +===== + +.. currentmodule:: farn.core.case + +.. autoclass:: Cases + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Cases.__init__ + ~Cases.add_parameters + ~Cases.append + ~Cases.clear + ~Cases.copy + ~Cases.count + ~Cases.extend + ~Cases.filter + ~Cases.index + ~Cases.insert + ~Cases.pop + ~Cases.remove + ~Cases.reverse + ~Cases.sort + ~Cases.to_numpy + ~Cases.to_pandas + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/farn.core.case.rst.txt b/_sources/_autosummary/farn.core.case.rst.txt new file mode 100644 index 00000000..3df058f8 --- /dev/null +++ b/_sources/_autosummary/farn.core.case.rst.txt @@ -0,0 +1,19 @@ +farn.core.case +============== + +.. automodule:: farn.core.case + :members: + :exclude-members: Case,CaseStatus,Cases, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + Case + CaseStatus + Cases + \ No newline at end of file diff --git a/_sources/_autosummary/farn.core.parameter.Parameter.rst.txt b/_sources/_autosummary/farn.core.parameter.Parameter.rst.txt new file mode 100644 index 00000000..657f7d15 --- /dev/null +++ b/_sources/_autosummary/farn.core.parameter.Parameter.rst.txt @@ -0,0 +1,30 @@ +Parameter +========= + +.. currentmodule:: farn.core.parameter + +.. autoclass:: Parameter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Parameter.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Parameter.dtype + ~Parameter.type + + \ No newline at end of file diff --git a/_sources/_autosummary/farn.core.parameter.rst.txt b/_sources/_autosummary/farn.core.parameter.rst.txt new file mode 100644 index 00000000..af5a9921 --- /dev/null +++ b/_sources/_autosummary/farn.core.parameter.rst.txt @@ -0,0 +1,17 @@ +farn.core.parameter +=================== + +.. automodule:: farn.core.parameter + :members: + :exclude-members: Parameter, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + Parameter + \ No newline at end of file diff --git a/_sources/_autosummary/farn.core.rst.txt b/_sources/_autosummary/farn.core.rst.txt new file mode 100644 index 00000000..d4b59cc5 --- /dev/null +++ b/_sources/_autosummary/farn.core.rst.txt @@ -0,0 +1,16 @@ +farn.core +========= + +.. automodule:: farn.core + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + case + parameter diff --git a/_sources/_autosummary/farn.farn.rst.txt b/_sources/_autosummary/farn.farn.rst.txt new file mode 100644 index 00000000..f38e6558 --- /dev/null +++ b/_sources/_autosummary/farn.farn.rst.txt @@ -0,0 +1,19 @@ +farn.farn +========= + +.. automodule:: farn.farn + :members: + + + + .. rubric:: Functions + .. autosummary:: + + create_case_folders + create_case_list_files + create_cases + create_param_dict_files + create_samples + execute_command_set + run_farn + \ No newline at end of file diff --git a/_sources/_autosummary/farn.run.batchProcess.AsyncBatchProcessor.rst.txt b/_sources/_autosummary/farn.run.batchProcess.AsyncBatchProcessor.rst.txt new file mode 100644 index 00000000..677aaa4c --- /dev/null +++ b/_sources/_autosummary/farn.run.batchProcess.AsyncBatchProcessor.rst.txt @@ -0,0 +1,25 @@ +AsyncBatchProcessor +=================== + +.. currentmodule:: farn.run.batchProcess + +.. autoclass:: AsyncBatchProcessor + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~AsyncBatchProcessor.__init__ + ~AsyncBatchProcessor.run + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/farn.run.batchProcess.rst.txt b/_sources/_autosummary/farn.run.batchProcess.rst.txt new file mode 100644 index 00000000..343844b2 --- /dev/null +++ b/_sources/_autosummary/farn.run.batchProcess.rst.txt @@ -0,0 +1,17 @@ +farn.run.batchProcess +===================== + +.. automodule:: farn.run.batchProcess + :members: + :exclude-members: AsyncBatchProcessor, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + AsyncBatchProcessor + \ No newline at end of file diff --git a/_sources/_autosummary/farn.run.cli.batchProcess.rst.txt b/_sources/_autosummary/farn.run.cli.batchProcess.rst.txt new file mode 100644 index 00000000..8a0c6e23 --- /dev/null +++ b/_sources/_autosummary/farn.run.cli.batchProcess.rst.txt @@ -0,0 +1,13 @@ +farn.run.cli.batchProcess +========================= + +.. automodule:: farn.run.cli.batchProcess + :members: + + + + .. rubric:: Functions + .. autosummary:: + + main + \ No newline at end of file diff --git a/_sources/_autosummary/farn.run.cli.rst.txt b/_sources/_autosummary/farn.run.cli.rst.txt new file mode 100644 index 00000000..6e40da73 --- /dev/null +++ b/_sources/_autosummary/farn.run.cli.rst.txt @@ -0,0 +1,15 @@ +farn.run.cli +============ + +.. automodule:: farn.run.cli + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + batchProcess diff --git a/_sources/_autosummary/farn.run.rst.txt b/_sources/_autosummary/farn.run.rst.txt new file mode 100644 index 00000000..57069ad2 --- /dev/null +++ b/_sources/_autosummary/farn.run.rst.txt @@ -0,0 +1,18 @@ +farn.run +======== + +.. automodule:: farn.run + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + batchProcess + cli + subProcess + utils diff --git a/_sources/_autosummary/farn.run.subProcess.rst.txt b/_sources/_autosummary/farn.run.subProcess.rst.txt new file mode 100644 index 00000000..3ad54099 --- /dev/null +++ b/_sources/_autosummary/farn.run.subProcess.rst.txt @@ -0,0 +1,13 @@ +farn.run.subProcess +=================== + +.. automodule:: farn.run.subProcess + :members: + + + + .. rubric:: Functions + .. autosummary:: + + execute_in_sub_process + \ No newline at end of file diff --git a/_sources/_autosummary/farn.run.utils.rst.txt b/_sources/_autosummary/farn.run.utils.rst.txt new file mode 100644 index 00000000..6b321d0a --- /dev/null +++ b/_sources/_autosummary/farn.run.utils.rst.txt @@ -0,0 +1,15 @@ +farn.run.utils +============== + +.. automodule:: farn.run.utils + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + threading diff --git a/_sources/_autosummary/farn.run.utils.threading.JobQueue.rst.txt b/_sources/_autosummary/farn.run.utils.threading.JobQueue.rst.txt new file mode 100644 index 00000000..20f61091 --- /dev/null +++ b/_sources/_autosummary/farn.run.utils.threading.JobQueue.rst.txt @@ -0,0 +1,34 @@ +JobQueue +======== + +.. currentmodule:: farn.run.utils.threading + +.. autoclass:: JobQueue + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~JobQueue.__init__ + ~JobQueue.empty + ~JobQueue.full + ~JobQueue.get + ~JobQueue.get_nowait + ~JobQueue.join + ~JobQueue.put + ~JobQueue.put_callable + ~JobQueue.put_nowait + ~JobQueue.qsize + ~JobQueue.task_done + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/farn.run.utils.threading.Worker.rst.txt b/_sources/_autosummary/farn.run.utils.threading.Worker.rst.txt new file mode 100644 index 00000000..35dc0a93 --- /dev/null +++ b/_sources/_autosummary/farn.run.utils.threading.Worker.rst.txt @@ -0,0 +1,40 @@ +Worker +====== + +.. currentmodule:: farn.run.utils.threading + +.. autoclass:: Worker + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Worker.__init__ + ~Worker.getName + ~Worker.isDaemon + ~Worker.is_alive + ~Worker.join + ~Worker.run + ~Worker.setDaemon + ~Worker.setName + ~Worker.start + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Worker.daemon + ~Worker.ident + ~Worker.name + ~Worker.native_id + + \ No newline at end of file diff --git a/_sources/_autosummary/farn.run.utils.threading.rst.txt b/_sources/_autosummary/farn.run.utils.threading.rst.txt new file mode 100644 index 00000000..0512aa3f --- /dev/null +++ b/_sources/_autosummary/farn.run.utils.threading.rst.txt @@ -0,0 +1,18 @@ +farn.run.utils.threading +======================== + +.. automodule:: farn.run.utils.threading + :members: + :exclude-members: JobQueue,Worker, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + JobQueue + Worker + \ No newline at end of file diff --git a/_sources/_autosummary/farn.sampling.rst.txt b/_sources/_autosummary/farn.sampling.rst.txt new file mode 100644 index 00000000..5b160338 --- /dev/null +++ b/_sources/_autosummary/farn.sampling.rst.txt @@ -0,0 +1,15 @@ +farn.sampling +============= + +.. automodule:: farn.sampling + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + sampling diff --git a/_sources/_autosummary/farn.sampling.sampling.DiscreteSampling.rst.txt b/_sources/_autosummary/farn.sampling.sampling.DiscreteSampling.rst.txt new file mode 100644 index 00000000..e94f4d52 --- /dev/null +++ b/_sources/_autosummary/farn.sampling.sampling.DiscreteSampling.rst.txt @@ -0,0 +1,27 @@ +DiscreteSampling +================ + +.. currentmodule:: farn.sampling.sampling + +.. autoclass:: DiscreteSampling + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~DiscreteSampling.__init__ + ~DiscreteSampling.generate_samples + ~DiscreteSampling.set_sampling_parameters + ~DiscreteSampling.set_sampling_type + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/farn.sampling.sampling.rst.txt b/_sources/_autosummary/farn.sampling.sampling.rst.txt new file mode 100644 index 00000000..afe8a84b --- /dev/null +++ b/_sources/_autosummary/farn.sampling.sampling.rst.txt @@ -0,0 +1,17 @@ +farn.sampling.sampling +====================== + +.. automodule:: farn.sampling.sampling + :members: + :exclude-members: DiscreteSampling, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + DiscreteSampling + \ No newline at end of file diff --git a/_sources/_autosummary/farn.utils.logging.rst.txt b/_sources/_autosummary/farn.utils.logging.rst.txt new file mode 100644 index 00000000..5d284e6b --- /dev/null +++ b/_sources/_autosummary/farn.utils.logging.rst.txt @@ -0,0 +1,14 @@ +farn.utils.logging +================== + +.. automodule:: farn.utils.logging + :members: + + + + .. rubric:: Functions + .. autosummary:: + + configure_logging + plural + \ No newline at end of file diff --git a/_sources/_autosummary/farn.utils.os.rst.txt b/_sources/_autosummary/farn.utils.os.rst.txt new file mode 100644 index 00000000..2ff26f1c --- /dev/null +++ b/_sources/_autosummary/farn.utils.os.rst.txt @@ -0,0 +1,13 @@ +farn.utils.os +============= + +.. automodule:: farn.utils.os + :members: + + + + .. rubric:: Functions + .. autosummary:: + + append_system_variable + \ No newline at end of file diff --git a/_sources/_autosummary/farn.utils.rst.txt b/_sources/_autosummary/farn.utils.rst.txt new file mode 100644 index 00000000..5ce3d26e --- /dev/null +++ b/_sources/_autosummary/farn.utils.rst.txt @@ -0,0 +1,16 @@ +farn.utils +========== + +.. automodule:: farn.utils + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + logging + os diff --git a/_sources/_autosummary/ospx.component.Component.rst.txt b/_sources/_autosummary/ospx.component.Component.rst.txt new file mode 100644 index 00000000..b34201bc --- /dev/null +++ b/_sources/_autosummary/ospx.component.Component.rst.txt @@ -0,0 +1,33 @@ +Component +========= + +.. currentmodule:: ospx.component + +.. autoclass:: Component + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Component.__init__ + ~Component.write_osp_model_description_xml + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Component.connectors + ~Component.units + ~Component.variables + ~Component.variables_with_start_values + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.component.RemoteAccess.rst.txt b/_sources/_autosummary/ospx.component.RemoteAccess.rst.txt new file mode 100644 index 00000000..3e8538fc --- /dev/null +++ b/_sources/_autosummary/ospx.component.RemoteAccess.rst.txt @@ -0,0 +1,30 @@ +RemoteAccess +============ + +.. currentmodule:: ospx.component + +.. autoclass:: RemoteAccess + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~RemoteAccess.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~RemoteAccess.port + ~RemoteAccess.host + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.component.rst.txt b/_sources/_autosummary/ospx.component.rst.txt new file mode 100644 index 00000000..2e552436 --- /dev/null +++ b/_sources/_autosummary/ospx.component.rst.txt @@ -0,0 +1,18 @@ +ospx.component +============== + +.. automodule:: ospx.component + :members: + :exclude-members: Component,RemoteAccess, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + Component + RemoteAccess + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.connection.Connection.rst.txt b/_sources/_autosummary/ospx.connection.Connection.rst.txt new file mode 100644 index 00000000..8b20fd07 --- /dev/null +++ b/_sources/_autosummary/ospx.connection.Connection.rst.txt @@ -0,0 +1,31 @@ +Connection +========== + +.. currentmodule:: ospx.connection + +.. autoclass:: Connection + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Connection.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Connection.is_valid + ~Connection.is_variable_connection + ~Connection.is_variable_group_connection + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.connection.Endpoint.rst.txt b/_sources/_autosummary/ospx.connection.Endpoint.rst.txt new file mode 100644 index 00000000..abedc6d5 --- /dev/null +++ b/_sources/_autosummary/ospx.connection.Endpoint.rst.txt @@ -0,0 +1,32 @@ +Endpoint +======== + +.. currentmodule:: ospx.connection + +.. autoclass:: Endpoint + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Endpoint.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Endpoint.connector + ~Endpoint.is_valid + ~Endpoint.variable + ~Endpoint.variable_name + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.connection.rst.txt b/_sources/_autosummary/ospx.connection.rst.txt new file mode 100644 index 00000000..accad2bf --- /dev/null +++ b/_sources/_autosummary/ospx.connection.rst.txt @@ -0,0 +1,18 @@ +ospx.connection +=============== + +.. automodule:: ospx.connection + :members: + :exclude-members: Connection,Endpoint, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + Connection + Endpoint + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.connector.Connector.rst.txt b/_sources/_autosummary/ospx.connector.Connector.rst.txt new file mode 100644 index 00000000..c4f62d83 --- /dev/null +++ b/_sources/_autosummary/ospx.connector.Connector.rst.txt @@ -0,0 +1,34 @@ +Connector +========= + +.. currentmodule:: ospx.connector + +.. autoclass:: Connector + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Connector.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Connector.is_group_connector + ~Connector.is_single_connector + ~Connector.type + ~Connector.variable + ~Connector.variable_group + ~Connector.variable_name + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.connector.rst.txt b/_sources/_autosummary/ospx.connector.rst.txt new file mode 100644 index 00000000..09ea5c2c --- /dev/null +++ b/_sources/_autosummary/ospx.connector.rst.txt @@ -0,0 +1,17 @@ +ospx.connector +============== + +.. automodule:: ospx.connector + :members: + :exclude-members: Connector, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + Connector + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.experiment.Experiment.rst.txt b/_sources/_autosummary/ospx.fmi.experiment.Experiment.rst.txt new file mode 100644 index 00000000..b6ce6c9e --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.experiment.Experiment.rst.txt @@ -0,0 +1,32 @@ +Experiment +========== + +.. currentmodule:: ospx.fmi.experiment + +.. autoclass:: Experiment + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Experiment.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Experiment.start_time + ~Experiment.step_size + ~Experiment.stop_time + ~Experiment.tolerance + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.experiment.rst.txt b/_sources/_autosummary/ospx.fmi.experiment.rst.txt new file mode 100644 index 00000000..11354110 --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.experiment.rst.txt @@ -0,0 +1,17 @@ +ospx.fmi.experiment +=================== + +.. automodule:: ospx.fmi.experiment + :members: + :exclude-members: Experiment, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + Experiment + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.fmu.FMU.rst.txt b/_sources/_autosummary/ospx.fmi.fmu.FMU.rst.txt new file mode 100644 index 00000000..9bf7e923 --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.fmu.FMU.rst.txt @@ -0,0 +1,33 @@ +FMU +=== + +.. currentmodule:: ospx.fmi.fmu + +.. autoclass:: FMU + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~FMU.__init__ + ~FMU.copy + ~FMU.proxify + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~FMU.default_experiment + ~FMU.units + ~FMU.variables + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.fmu.rst.txt b/_sources/_autosummary/ospx.fmi.fmu.rst.txt new file mode 100644 index 00000000..0955f2ae --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.fmu.rst.txt @@ -0,0 +1,17 @@ +ospx.fmi.fmu +============ + +.. automodule:: ospx.fmi.fmu + :members: + :exclude-members: FMU, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + FMU + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.rst.txt b/_sources/_autosummary/ospx.fmi.rst.txt new file mode 100644 index 00000000..c5813131 --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.rst.txt @@ -0,0 +1,18 @@ +ospx.fmi +======== + +.. automodule:: ospx.fmi + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + experiment + fmu + unit + variable diff --git a/_sources/_autosummary/ospx.fmi.unit.BaseUnit.rst.txt b/_sources/_autosummary/ospx.fmi.unit.BaseUnit.rst.txt new file mode 100644 index 00000000..669923b2 --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.unit.BaseUnit.rst.txt @@ -0,0 +1,38 @@ +BaseUnit +======== + +.. currentmodule:: ospx.fmi.unit + +.. autoclass:: BaseUnit + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~BaseUnit.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~BaseUnit.A + ~BaseUnit.K + ~BaseUnit.cd + ~BaseUnit.factor + ~BaseUnit.kg + ~BaseUnit.m + ~BaseUnit.mol + ~BaseUnit.offset + ~BaseUnit.rad + ~BaseUnit.s + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.unit.DisplayUnit.rst.txt b/_sources/_autosummary/ospx.fmi.unit.DisplayUnit.rst.txt new file mode 100644 index 00000000..a299118f --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.unit.DisplayUnit.rst.txt @@ -0,0 +1,31 @@ +DisplayUnit +=========== + +.. currentmodule:: ospx.fmi.unit + +.. autoclass:: DisplayUnit + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~DisplayUnit.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~DisplayUnit.factor + ~DisplayUnit.offset + ~DisplayUnit.name + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.unit.Unit.rst.txt b/_sources/_autosummary/ospx.fmi.unit.Unit.rst.txt new file mode 100644 index 00000000..c03deca8 --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.unit.Unit.rst.txt @@ -0,0 +1,31 @@ +Unit +==== + +.. currentmodule:: ospx.fmi.unit + +.. autoclass:: Unit + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Unit.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Unit.base_unit + ~Unit.name + ~Unit.display_unit + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.unit.rst.txt b/_sources/_autosummary/ospx.fmi.unit.rst.txt new file mode 100644 index 00000000..8e8b615b --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.unit.rst.txt @@ -0,0 +1,19 @@ +ospx.fmi.unit +============= + +.. automodule:: ospx.fmi.unit + :members: + :exclude-members: BaseUnit,DisplayUnit,Unit, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + BaseUnit + DisplayUnit + Unit + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.variable.ScalarVariable.rst.txt b/_sources/_autosummary/ospx.fmi.variable.ScalarVariable.rst.txt new file mode 100644 index 00000000..73b7da71 --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.variable.ScalarVariable.rst.txt @@ -0,0 +1,32 @@ +ScalarVariable +============== + +.. currentmodule:: ospx.fmi.variable + +.. autoclass:: ScalarVariable + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~ScalarVariable.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~ScalarVariable.causality + ~ScalarVariable.data_type + ~ScalarVariable.start + ~ScalarVariable.variability + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.fmi.variable.rst.txt b/_sources/_autosummary/ospx.fmi.variable.rst.txt new file mode 100644 index 00000000..1be32127 --- /dev/null +++ b/_sources/_autosummary/ospx.fmi.variable.rst.txt @@ -0,0 +1,22 @@ +ospx.fmi.variable +================= + +.. automodule:: ospx.fmi.variable + :members: + :exclude-members: ScalarVariable, + + + + + .. rubric:: Functions + .. autosummary:: + + get_fmi_data_type + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + ScalarVariable + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.graph.Graph.rst.txt b/_sources/_autosummary/ospx.graph.Graph.rst.txt new file mode 100644 index 00000000..a2d50565 --- /dev/null +++ b/_sources/_autosummary/ospx.graph.Graph.rst.txt @@ -0,0 +1,25 @@ +Graph +===== + +.. currentmodule:: ospx.graph + +.. autoclass:: Graph + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Graph.__init__ + ~Graph.generate_dependency_graph + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.graph.rst.txt b/_sources/_autosummary/ospx.graph.rst.txt new file mode 100644 index 00000000..b40bef59 --- /dev/null +++ b/_sources/_autosummary/ospx.graph.rst.txt @@ -0,0 +1,17 @@ +ospx.graph +========== + +.. automodule:: ospx.graph + :members: + :exclude-members: Graph, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + Graph + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.importer.OspSystemStructureImporter.rst.txt b/_sources/_autosummary/ospx.importer.OspSystemStructureImporter.rst.txt new file mode 100644 index 00000000..1f47a057 --- /dev/null +++ b/_sources/_autosummary/ospx.importer.OspSystemStructureImporter.rst.txt @@ -0,0 +1,25 @@ +OspSystemStructureImporter +========================== + +.. currentmodule:: ospx.importer + +.. autoclass:: OspSystemStructureImporter + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~OspSystemStructureImporter.__init__ + ~OspSystemStructureImporter.import_system_structure + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.importer.rst.txt b/_sources/_autosummary/ospx.importer.rst.txt new file mode 100644 index 00000000..0b87fa88 --- /dev/null +++ b/_sources/_autosummary/ospx.importer.rst.txt @@ -0,0 +1,17 @@ +ospx.importer +============= + +.. automodule:: ospx.importer + :members: + :exclude-members: OspSystemStructureImporter, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + OspSystemStructureImporter + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.ospCaseBuilder.OspCaseBuilder.rst.txt b/_sources/_autosummary/ospx.ospCaseBuilder.OspCaseBuilder.rst.txt new file mode 100644 index 00000000..26e54c09 --- /dev/null +++ b/_sources/_autosummary/ospx.ospCaseBuilder.OspCaseBuilder.rst.txt @@ -0,0 +1,25 @@ +OspCaseBuilder +============== + +.. currentmodule:: ospx.ospCaseBuilder + +.. autoclass:: OspCaseBuilder + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~OspCaseBuilder.__init__ + ~OspCaseBuilder.build + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.ospCaseBuilder.rst.txt b/_sources/_autosummary/ospx.ospCaseBuilder.rst.txt new file mode 100644 index 00000000..28c0dfb4 --- /dev/null +++ b/_sources/_autosummary/ospx.ospCaseBuilder.rst.txt @@ -0,0 +1,17 @@ +ospx.ospCaseBuilder +=================== + +.. automodule:: ospx.ospCaseBuilder + :members: + :exclude-members: OspCaseBuilder, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + OspCaseBuilder + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.ospSimulationCase.OspSimulationCase.rst.txt b/_sources/_autosummary/ospx.ospSimulationCase.OspSimulationCase.rst.txt new file mode 100644 index 00000000..3fd2dd7c --- /dev/null +++ b/_sources/_autosummary/ospx.ospSimulationCase.OspSimulationCase.rst.txt @@ -0,0 +1,29 @@ +OspSimulationCase +================= + +.. currentmodule:: ospx.ospSimulationCase + +.. autoclass:: OspSimulationCase + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~OspSimulationCase.__init__ + ~OspSimulationCase.setup + ~OspSimulationCase.write_osp_system_structure_xml + ~OspSimulationCase.write_statistics_dict + ~OspSimulationCase.write_system_structure_ssd + ~OspSimulationCase.write_watch_dict + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.ospSimulationCase.rst.txt b/_sources/_autosummary/ospx.ospSimulationCase.rst.txt new file mode 100644 index 00000000..f4483811 --- /dev/null +++ b/_sources/_autosummary/ospx.ospSimulationCase.rst.txt @@ -0,0 +1,17 @@ +ospx.ospSimulationCase +====================== + +.. automodule:: ospx.ospSimulationCase + :members: + :exclude-members: OspSimulationCase, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + OspSimulationCase + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.simulation.Simulation.rst.txt b/_sources/_autosummary/ospx.simulation.Simulation.rst.txt new file mode 100644 index 00000000..1678d94e --- /dev/null +++ b/_sources/_autosummary/ospx.simulation.Simulation.rst.txt @@ -0,0 +1,33 @@ +Simulation +========== + +.. currentmodule:: ospx.simulation + +.. autoclass:: Simulation + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~Simulation.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~Simulation.algorithm + ~Simulation.base_step_size + ~Simulation.name + ~Simulation.start_time + ~Simulation.stop_time + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.simulation.rst.txt b/_sources/_autosummary/ospx.simulation.rst.txt new file mode 100644 index 00000000..5c69b027 --- /dev/null +++ b/_sources/_autosummary/ospx.simulation.rst.txt @@ -0,0 +1,17 @@ +ospx.simulation +=============== + +.. automodule:: ospx.simulation + :members: + :exclude-members: Simulation, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + Simulation + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.system.System.rst.txt b/_sources/_autosummary/ospx.system.System.rst.txt new file mode 100644 index 00000000..1ccaf50e --- /dev/null +++ b/_sources/_autosummary/ospx.system.System.rst.txt @@ -0,0 +1,34 @@ +System +====== + +.. currentmodule:: ospx.system + +.. autoclass:: System + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~System.__init__ + + + + + + + .. rubric:: Attributes + .. autosummary:: + + ~System.components + ~System.connections + ~System.connectors + ~System.fmus + ~System.units + ~System.variables + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.system.rst.txt b/_sources/_autosummary/ospx.system.rst.txt new file mode 100644 index 00000000..69f7a787 --- /dev/null +++ b/_sources/_autosummary/ospx.system.rst.txt @@ -0,0 +1,17 @@ +ospx.system +=========== + +.. automodule:: ospx.system + :members: + :exclude-members: System, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + System + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.utils.dateTime.rst.txt b/_sources/_autosummary/ospx.utils.dateTime.rst.txt new file mode 100644 index 00000000..894253f1 --- /dev/null +++ b/_sources/_autosummary/ospx.utils.dateTime.rst.txt @@ -0,0 +1,13 @@ +ospx.utils.dateTime +=================== + +.. automodule:: ospx.utils.dateTime + :members: + + + + .. rubric:: Functions + .. autosummary:: + + calc_time + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.utils.dict.rst.txt b/_sources/_autosummary/ospx.utils.dict.rst.txt new file mode 100644 index 00000000..06f9db82 --- /dev/null +++ b/_sources/_autosummary/ospx.utils.dict.rst.txt @@ -0,0 +1,16 @@ +ospx.utils.dict +=============== + +.. automodule:: ospx.utils.dict + :members: + + + + .. rubric:: Functions + .. autosummary:: + + find_key + find_keys + find_type_identifier_in_keys + shrink_dict + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.utils.logging.rst.txt b/_sources/_autosummary/ospx.utils.logging.rst.txt new file mode 100644 index 00000000..c2458479 --- /dev/null +++ b/_sources/_autosummary/ospx.utils.logging.rst.txt @@ -0,0 +1,13 @@ +ospx.utils.logging +================== + +.. automodule:: ospx.utils.logging + :members: + + + + .. rubric:: Functions + .. autosummary:: + + configure_logging + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.utils.plotting.rst.txt b/_sources/_autosummary/ospx.utils.plotting.rst.txt new file mode 100644 index 00000000..235822a6 --- /dev/null +++ b/_sources/_autosummary/ospx.utils.plotting.rst.txt @@ -0,0 +1,14 @@ +ospx.utils.plotting +=================== + +.. automodule:: ospx.utils.plotting + :members: + + + + .. rubric:: Functions + .. autosummary:: + + create_meta_dict + save_figure + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.utils.rst.txt b/_sources/_autosummary/ospx.utils.rst.txt new file mode 100644 index 00000000..3c7f088d --- /dev/null +++ b/_sources/_autosummary/ospx.utils.rst.txt @@ -0,0 +1,19 @@ +ospx.utils +========== + +.. automodule:: ospx.utils + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + dateTime + dict + logging + plotting + zip diff --git a/_sources/_autosummary/ospx.utils.zip.rst.txt b/_sources/_autosummary/ospx.utils.zip.rst.txt new file mode 100644 index 00000000..c1049980 --- /dev/null +++ b/_sources/_autosummary/ospx.utils.zip.rst.txt @@ -0,0 +1,18 @@ +ospx.utils.zip +============== + +.. automodule:: ospx.utils.zip + :members: + + + + .. rubric:: Functions + .. autosummary:: + + add_file_content_to_zip + read_file_content_from_zip + remove_files_from_zip + rename_file_in_zip + substitute_text_in_zip + update_file_content_in_zip + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.watch.cli.rst.txt b/_sources/_autosummary/ospx.watch.cli.rst.txt new file mode 100644 index 00000000..4f435752 --- /dev/null +++ b/_sources/_autosummary/ospx.watch.cli.rst.txt @@ -0,0 +1,15 @@ +ospx.watch.cli +============== + +.. automodule:: ospx.watch.cli + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + watchCosim diff --git a/_sources/_autosummary/ospx.watch.cli.watchCosim.rst.txt b/_sources/_autosummary/ospx.watch.cli.watchCosim.rst.txt new file mode 100644 index 00000000..03a866b4 --- /dev/null +++ b/_sources/_autosummary/ospx.watch.cli.watchCosim.rst.txt @@ -0,0 +1,13 @@ +ospx.watch.cli.watchCosim +========================= + +.. automodule:: ospx.watch.cli.watchCosim + :members: + + + + .. rubric:: Functions + .. autosummary:: + + main + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.watch.rst.txt b/_sources/_autosummary/ospx.watch.rst.txt new file mode 100644 index 00000000..7b38e28b --- /dev/null +++ b/_sources/_autosummary/ospx.watch.rst.txt @@ -0,0 +1,16 @@ +ospx.watch +========== + +.. automodule:: ospx.watch + :members: + + + +.. rubric:: Modules +.. autosummary:: + :toctree: + :template: custom-module.rst + :recursive: + + cli + watchCosim diff --git a/_sources/_autosummary/ospx.watch.watchCosim.CosimWatcher.rst.txt b/_sources/_autosummary/ospx.watch.watchCosim.CosimWatcher.rst.txt new file mode 100644 index 00000000..cbcfd965 --- /dev/null +++ b/_sources/_autosummary/ospx.watch.watchCosim.CosimWatcher.rst.txt @@ -0,0 +1,27 @@ +CosimWatcher +============ + +.. currentmodule:: ospx.watch.watchCosim + +.. autoclass:: CosimWatcher + :members: + :show-inheritance: + + + + .. automethod:: __init__ + + .. rubric:: Methods + .. autosummary:: + + ~CosimWatcher.__init__ + ~CosimWatcher.dump + ~CosimWatcher.plot + ~CosimWatcher.read_watch_dict + + + + + + + \ No newline at end of file diff --git a/_sources/_autosummary/ospx.watch.watchCosim.rst.txt b/_sources/_autosummary/ospx.watch.watchCosim.rst.txt new file mode 100644 index 00000000..377215a9 --- /dev/null +++ b/_sources/_autosummary/ospx.watch.watchCosim.rst.txt @@ -0,0 +1,17 @@ +ospx.watch.watchCosim +===================== + +.. automodule:: ospx.watch.watchCosim + :members: + :exclude-members: CosimWatcher, + + + + + .. rubric:: Classes + .. autosummary:: + :toctree: + :template: custom-class.rst + + CosimWatcher + \ No newline at end of file diff --git a/_sources/api.rst.txt b/_sources/api.rst.txt new file mode 100644 index 00000000..27c1722f --- /dev/null +++ b/_sources/api.rst.txt @@ -0,0 +1,10 @@ +API Documentation +================= + +.. toctree:: + :maxdepth: 4 + + farn + ospx + dictIO + farn_example diff --git a/_sources/changelogs.rst.txt b/_sources/changelogs.rst.txt new file mode 100644 index 00000000..cf1c6b5b --- /dev/null +++ b/_sources/changelogs.rst.txt @@ -0,0 +1,9 @@ +Changelogs +========== + +.. toctree:: + :maxdepth: 4 + + CHANGELOG_farn + CHANGELOG_ospx + CHANGELOG_dictIO diff --git a/_sources/cli.batchProcess.rst.txt b/_sources/cli.batchProcess.rst.txt new file mode 100644 index 00000000..23e7516a --- /dev/null +++ b/_sources/cli.batchProcess.rst.txt @@ -0,0 +1,3 @@ +.. sphinx_argparse_cli:: + :module: farn.run.cli.batchProcess + :func: _argparser diff --git a/_sources/cli.dict_parser.rst.txt b/_sources/cli.dict_parser.rst.txt new file mode 100644 index 00000000..d534b266 --- /dev/null +++ b/_sources/cli.dict_parser.rst.txt @@ -0,0 +1,3 @@ +.. sphinx_argparse_cli:: + :module: dictIO.cli.dict_parser + :func: _argparser diff --git a/_sources/cli.farn.rst.txt b/_sources/cli.farn.rst.txt new file mode 100644 index 00000000..1eb4272d --- /dev/null +++ b/_sources/cli.farn.rst.txt @@ -0,0 +1,3 @@ +.. sphinx_argparse_cli:: + :module: farn.cli.farn + :func: _argparser diff --git a/_sources/cli.importSystemStructure.rst.txt b/_sources/cli.importSystemStructure.rst.txt new file mode 100644 index 00000000..bc19807f --- /dev/null +++ b/_sources/cli.importSystemStructure.rst.txt @@ -0,0 +1,3 @@ +.. sphinx_argparse_cli:: + :module: ospx.cli.importSystemStructure + :func: _argparser diff --git a/_sources/cli.ospCaseBuilder.rst.txt b/_sources/cli.ospCaseBuilder.rst.txt new file mode 100644 index 00000000..806b1195 --- /dev/null +++ b/_sources/cli.ospCaseBuilder.rst.txt @@ -0,0 +1,3 @@ +.. sphinx_argparse_cli:: + :module: ospx.cli.ospCaseBuilder + :func: _argparser diff --git a/_sources/cli.rst.txt b/_sources/cli.rst.txt new file mode 100644 index 00000000..0d3f6b1c --- /dev/null +++ b/_sources/cli.rst.txt @@ -0,0 +1,9 @@ +CLI Documentation +================= + +.. toctree:: + :maxdepth: 4 + + cli.sub.farn + cli.sub.ospx + cli.sub.dictIO diff --git a/_sources/cli.sub.dictIO.rst.txt b/_sources/cli.sub.dictIO.rst.txt new file mode 100644 index 00000000..e9402a86 --- /dev/null +++ b/_sources/cli.sub.dictIO.rst.txt @@ -0,0 +1,7 @@ +dictIO +------ + +.. toctree:: + :maxdepth: 3 + + cli.dictParser diff --git a/_sources/cli.sub.farn.rst.txt b/_sources/cli.sub.farn.rst.txt new file mode 100644 index 00000000..be3a008d --- /dev/null +++ b/_sources/cli.sub.farn.rst.txt @@ -0,0 +1,8 @@ +farn +---- + +.. toctree:: + :maxdepth: 3 + + cli.farn + cli.batchProcess diff --git a/_sources/cli.sub.ospx.rst.txt b/_sources/cli.sub.ospx.rst.txt new file mode 100644 index 00000000..36f0b1b3 --- /dev/null +++ b/_sources/cli.sub.ospx.rst.txt @@ -0,0 +1,9 @@ +ospx +---- + +.. toctree:: + :maxdepth: 3 + + cli.ospCaseBuilder + cli.importSystemStructure + cli.watchCosim diff --git a/_sources/cli.watchCosim.rst.txt b/_sources/cli.watchCosim.rst.txt new file mode 100644 index 00000000..b76b1fac --- /dev/null +++ b/_sources/cli.watchCosim.rst.txt @@ -0,0 +1,3 @@ +.. sphinx_argparse_cli:: + :module: ospx.watch.cli.watchCosim + :func: _argparser diff --git a/_sources/dictIO.rst.txt b/_sources/dictIO.rst.txt new file mode 100644 index 00000000..f04ed4c1 --- /dev/null +++ b/_sources/dictIO.rst.txt @@ -0,0 +1,30 @@ +dictIO package +============== + +Subpackages +----------- + +.. autosummary:: + :toctree: _autosummary + :template: custom-module.rst + :recursive: + + dictIO.utils + + +Modules +------- + +.. autosummary:: + :toctree: _autosummary + :template: custom-module.rst + :recursive: + + dictIO.dict + dictIO.dict_parser + dictIO.dict_reader + dictIO.dict_writer + dictIO.formatter + dictIO.parser + dictIO.types + dictIO.cpp_dict diff --git a/_sources/farn.rst.txt b/_sources/farn.rst.txt new file mode 100644 index 00000000..703e23c3 --- /dev/null +++ b/_sources/farn.rst.txt @@ -0,0 +1,26 @@ +farn package +============ + +Subpackages +----------- + +.. autosummary:: + :toctree: _autosummary + :template: custom-module.rst + :recursive: + + farn.core + farn.run + farn.sampling + farn.utils + + +Modules +------- + +.. autosummary:: + :toctree: _autosummary + :template: custom-module.rst + :recursive: + + farn.farn diff --git a/_sources/farn_example.md.txt b/_sources/farn_example.md.txt new file mode 100644 index 00000000..0aefe80d --- /dev/null +++ b/_sources/farn_example.md.txt @@ -0,0 +1,181 @@ +# Example of farn API usage + +The following gives an example of how the farn API can be used in conjunction with OSP cosim and the ospx package. + +## Case + +Case is a simple dataclass designed to hold case-specific information as instance attributes.
+Below example uses the most typical / important ones: + +~~~py +from pathlib import Path +from typing import Dict, List +from farn.core import Case, Parameter + +case_name: str = "test_001" + +case_folder: Path = Path("path/to/your/experiment/cases") / case_name + +case_parameters: List[Parameter] = [ + Parameter("x1", 1.0), + Parameter("x2", 2.0), + Parameter("x3", 3.0), +] + +command_sets: Dict[str, List[str]] = { + "prepare": [ + "copy path/to/template/dir/caseDict .", # copy a (case-agnostic) ospx config file from a template directory into the case folder + "dictParser caseDict", # parse the ospx config file. This will make it case-specific + "ospCaseBuilder parsed.caseDict", # build the (case-specific) OspSystemStructure.xml + ], + "run": [ + "cosim run OspSystemStructure.xml -b 0 -d 10", # run OSP cosim + ], + "post": [ + "watchCosim -d watchDict", # optional post-processing. watchCosim creates a sub-folder 'results' in the case folder + ], +} + +case: Case = Case( + case=case_name, + path=case_folder, + is_leaf=True, + parameters=case_parameters, + command_sets=command_sets, +) +~~~ + + +## Cases + +Many farn functions expect not a single Case object, but a list of Case objects passed in.
+So, even if you create only a single Case object, you will likely need to wrap it in a Cases list for processing. + +~~~py +from farn.core import Cases + +cases: Cases = Cases() +cases.append(case) +~~~ + +## Create case folder(s) + +~~~py +from farn.farn import create_case_folders + +_ = create_case_folders(cases) +~~~ + +## Create paramDict file in case folder(s) + +It is a convention used by both farn and ospx that a 'paramDict' file is expected to exist in the case folder +which contains the case-specific values of all varied parameters.
+create_param_dict_files() will create this paramDict file in the case folder(s): + +~~~py +from farn.farn import create_param_dict_files + +_ = create_param_dict_files(cases) +~~~ + + +## Prepare OSP simulation case(s) + +Execute the command_set that performs preparatory tasks in your case folder(s). + +~~~py +from farn.farn import execute_command_set + +_ = execute_command_set( + cases=cases, + command_set="prepare", +) +~~~ + + +## Run OSP simulation case(s) + +Execute the command_set that actually runs your simulation case(s). + +~~~py +_ = execute_command_set( + cases=cases, + command_set="run", +) +~~~ + +## Execute post-processing (optional) + +Execute the command_set that performs post-processing tasks in your case folder(s) (if any). + +~~~py +_ = execute_command_set( + cases=cases, + command_set="post", +) +~~~ + +## Read results + +Reading results after your simulation cases finished can be rather individual and there will surely be multiple ways to accomplish this. +Two exemplary ways being + +a) You can read the *.csv files that cosim.exe generates, i.e. by reading them into a Pandas DataFrame. + +b) In case you executed watchCosim as a post-processing step, a sub-folder 'results' will exist in each case folder that contains the results additionally as a resultDict file. + +Variant a) is less complex and can be done with Pandas (no example given here).
+Variant b) offers some additional possibilities but requires also additional code.
+Below hence an example for variant b), i.e. how to read a resultDict file generated by watchCosim + +~~~py +from typing import Any, Dict, List +from pandas import DataFrame, Series +from dictIO import DictReader +from dictIO.utils.path import relative_path + +# @NOTE: Adjust 'component_name' and 'variable_name' to what is defined in your (FMU) model +# @NOTE: 'y' is just an example. Add mappings for more column names / variables as you like and need. +mapping: Dict[str, Dict[str, Any]] = { + "y": { # column name you want to map a variable to + "key": "component_name|variable_name:latestValue", # variable in FMU + "unit": 1, # usually 1, unless you want to apply a scaling factor + } +} + +# column names +names: List[str] = [name for name in mapping if not re.search("(^_|COMMENT)", name)] + +series: Dict[str, Series] = { + "path": Series(data=None, dtype=dtype(str), name="path"), +} + +for index, case in cases: + + case_folder: Path = case.path + result_folder: Path = case_folder / "results" + result_dict_file: Path = result_folder / "watchDict-test_project-resultDict" # adapt to output of watchCosim. + + series["path"].loc[index] = str(relative_path(Path.cwd(), case_folder)) + + result_dict = DictReader.read(result_dict_file, includes=False, comments=False) + + for name in names: + value: Any = None + value_eval_string = "result_dict['" + "']['".join(mapping[name]["key"].split(":")) + "']" + try: + value = eval(value_eval_string) + except Exception: + logger.warning(f'"{value_eval_string}" not in {result_dict_file}') + continue + + if name not in series: + series[name] = Series(data=None, dtype=dtype(type(value)), name=name) + + if value is not None: + series[name].loc[index] = value + +df: DataFrame = DataFrame(data=series) + +df.set_index("path", inplace=True) # optional. Makes the 'path' column the DataFrame's index +~~~ \ No newline at end of file diff --git a/_sources/fileFormat.caseDict.md.txt b/_sources/fileFormat.caseDict.md.txt new file mode 100644 index 00000000..2b30d340 --- /dev/null +++ b/_sources/fileFormat.caseDict.md.txt @@ -0,0 +1,300 @@ +# caseDict + +## Description + +A caseDict is a file in dictIO dict file format used with ospCaseBuilder + +A caseDict acts as input for ospCaseBuilder to +* generate an osp-compatible simulation case, consisting of one or multiple fmu's +* trigger subsequent actions, such as writing a statisticsDict and a default watchDict + +A caseDict file contains +* generic information about the simulation case and the physical location of the fmu's to be sourced +* information about the components and the names to be used within the simulation +* for each component, a dictionary of settings (e.g. start values and connector names) +* a connection routing between connectors defined in component sub-dictionary + +## Elements + +| element / key | type | Description | +| :------------------------------------------------ | :-------- | :---------- | +| #include | string | include directive. The specified dict file (e.g. a paramDict) will be read and merged into the caseDict | +| _environment | dict | environment variables needed by ospCaseBuilder at runtime | +|  libSource | string | relative or absolute path to the directory where the FMUs are located, i.e. the base folder of an FMU library. It acts as entry point for the FMU search. | +| systemStructure | dict | complete system structure | +|  components | dict | defines all component models used in the simulation | +|   \ | dict | unique name identifying a component in the simulation | +|    connectors | dict | itemization of connectors as defined in the FMU's modelDescription.xml | +|     \ | dict | speaking name of a connector, i.e. what it does and where it is mounted | +|      variable | string | name of a referenced variable as defined in the FMU file (mutually exclusive with variableGroup)| +|      variableGroup | string | name of a referenced VariableGroup as defined in _OSPModelDescription.xml (mutually exclusive with variable)| +|      type | string | type of the connector. Choices: {input, output} | +|    initialize | dict | optional initialization, updating the FMU's default settings | +|     \ | dict | the variable / parameter to be set. Needs to match the name as defined in the FMU file. | +|      causality | string | causality of the variable. Choices: {input, output, parameter} | +|      variability | string | variability of the variable. Choices: {fixed, calculated, tunable} | +|      start | float | initial value the variable shall be set to. | +|    fmu | string | relative path to the location of the source FMU (relative to libSource) | +|    stepSize | string | optional step size for this component. Only necessary in case the step size shall deviate from the default step size defined in the FMU's ModelDescription.xml | +|  connections | dict | itemization of connections | +|   \ | dict | speaking name of the connection | +|    source | dict | source endpoint of \ | +|     component | string | name of source \ | +|     connector | string | name of \ at source \ (mutually exclusive with variable) | +|     variable | string | name of \ at source \ (mutually exclusive with connector) | +|    target | dict | target endpoint of \ | +|     component | string | name of target \ | +|     connector | string | name of \ at target \ (mutually exclusive with variable) | +|     variable | string | name of \ at target \ (mutually exclusive with connector) | +| run | dict | settings for simulation run | +|  simulation | dict | additional information about the simulaton. Used for window decoration. | +|   name | string | name of the simulation | +|   startTime | float | start time | +|   stopTime | float | start time | +|   baseStepSize | float | master algorithm step size | +|   algorithm | string | Co-simulation master algorithm (currently 'fixedStep' is supported by OSP) | + +## Example + +Below example shows a typical caseDict file. + +~~~cpp +/*---------------------------------*- C++ -*----------------------------------*\ +filetype dictionary; coding utf-8; version 0.1; local --; purpose --; +\*----------------------------------------------------------------------------*/ +#include paramDict + +_environment +{ + libSource path/to/a/model/library/on/your/machine; +} +systemStructure +{ + connections + { + minuend_to_difference + { + source + { + component minuend; + connector minuend_output; + } + target + { + component difference; + connector difference_input_minuend; + } + } + subtrahend_to_difference + { + source + { + component subtrahend; + connector subtrahend_output; + } + target + { + component difference; + connector difference_input_subtrahend; + } + } + dividend_to_quotient + { + source + { + component dividend; + connector dividend_output; + } + target + { + component quotient; + connector quotient_input_dividend; + } + } + difference_to_divisor + { + source + { + component difference; + connector difference_output; + } + target + { + component quotient; + connector quotient_input_divisor; + } + } + } + components + { + difference + { + connectors + { + difference_input_minuend + { + variable difference.IN1; + type input; + } + difference_input_subtrahend + { + variable difference.IN2; + type input; + } + difference_output + { + variable difference.OUT; + type output; + } + } + fmu subfolder/in/your/library/difference.fmu; + } + quotient + { + connectors + { + quotient_input_dividend + { + variable quotient.IN1; + type input; + } + quotient_input_divisor + { + variable quotient.IN2; + type input; + } + quotient_output + { + variable quotient.OUT; + type output; + } + + } + fmu subfolder/in/your/library/quotient.fmu; + } + minuend + { + connectors + { + minuend_output + { + variable constVal.OUT; + type output; + } + } + initialize + { + constVal.IN + { + causality parameter; + variability fixed; + start $minuend; + } + } + fmu subfolder/in/your/library/constantVal.fmu; + } + subtrahend + { + connectors + { + subtrahend_output + { + variable constVal.OUT; + type output; + } + } + initialize + { + constVal.IN + { + causality parameter; + variability fixed; + start $subtrahend; + } + } + fmu subfolder/in/your/library/constantVal.fmu; + } + dividend + { + connectors + { + dividend_output + { + variable constVal.OUT; + type output; + } + } + initialize + { + constVal.IN + { + causality parameter; + variability fixed; + start $dividend; + } + } + fmu subfolder/in/your/library/constantVal.fmu; + } + } +} +run +{ + simulation + { + name demoCase; + startTime 0; + stopTime 10; + baseStepSize 0.01; + algorithm fixedStep; + } +} + +~~~ +If you aim for just a first inspection of a simulation case, all you need to do is drop all referenced FMUs +into the case's build directory and call ospCaseBuilder with the --inspect option: +``` +ospCaseBuilder caseDict --inspect --verbose +``` +Inspection works already with a fairly rudimentary caseDict, such as: +~~~cpp +/*---------------------------------*- C++ -*----------------------------------*\ +filetype dictionary; coding utf-8; version 0.1; local --; purpose --; +\*----------------------------------------------------------------------------*/ +_environment +{ + libSource path/to/a/model/library/on/your/machine; +} +systemStructure +{ + components + { + difference + { + fmu subfolder/in/your/library/difference.fmu; + } + quotient + { + fmu subfolder/in/your/library/quotient.fmu; + } + minuend + { + fmu subfolder/in/your/library/constantVal.fmu; + } + subtrahend + { + fmu subfolder/in/your/library/constantVal.fmu; + } + dividend + { + fmu subfolder/in/your/library/constantVal.fmu; + } + } +} +run +{ + simulation + { + name demoCase; + } +} +~~~ \ No newline at end of file diff --git a/_sources/fileFormat.farnDict.md.txt b/_sources/fileFormat.farnDict.md.txt new file mode 100644 index 00000000..8b72ca97 --- /dev/null +++ b/_sources/fileFormat.farnDict.md.txt @@ -0,0 +1,234 @@ +# farnDict + +## Description + +A farnDict is a file in dictIO dict file format used with farn + +A farnDict +* defines the layers, the parameters varied per layer and the related sampling used to create the samples per layer +* after sampling, the layers, parameters and generated samples per layer make up the designspace that farn traverses +* farn creates one distinct case folder for each sample, making up a nested case folder structure +* nest levels and -dimensions of the case folder structure follow the sequence of layers as defined in the farn dict + +## Elements + +| element / key | type | Description | +| :-----------------------------------------| :---------------------------- | :---------- | +| _environment | dict | [optional] dict with system variables set at runtime, commonly containing folder paths, which can subsequently be referenced in shell commands defined in _commands | +| _always | dict | dict defining all objects (as variables, dicts and arrays) which have to be distributed to all farn layers in case no additional farn layer shall be generated | +| _layers | dict | dict defining all layers. Each layer represents one nest level in the folder structure that will be generated by farn. | +|  \ | dict | unique key defining a layer. It serves as basename for all case folders in the nest level corresponding with that layer. | +|   _sampling | dict | dict defining sampling-type and -parameters of a layer | +|    _type | string | sampling type. Choices currently implemented are {'fixed', 'linSpace', 'uniformLhs', 'normalLhs', 'sobol', 'hilbertCurve'} | +|    _names | list[string] | list naming all variables / parameters being varied in this layer. For each variable / parameter named here, sampled values will be generated. | +|    _values | list[list[*float]] | (required for sampling type 'fixed'): List containing lists of fixed values. For each parameter name defined in _names, one list of fixed values must exist, i.e. the number of lists in _values must match the number of parameter names defined in _names. The number of values can freely be chosen. However, all lists in _values must have the same number of values. | +|    _ranges | list[list[float, float]] | (required for sampling types 'linSpace', 'uniformLhs' and 'hilbertCurve'): List containing ranges. A range is defined through the lower and upper boundary value for the related parameter name, given as tuple (minimum, maximum). For each parameter name defined in _names, one range tuple must exist. | +|    _numberOfSamples | int | (required for sampling types 'linSpace', 'uniformLhs' and 'hilbertCurve'): Number of samples to be generated. In case of 'linSpace', boundary values are included if an odd number of samples is given. In case of 'uniformLHS', the given number of samples will be generated within range (=between lower and upper boundary), excluding the boundaries themselves. | +|    _includeBoundingBox | bool | (optional, for sampling type 'uniformLhs', 'sobol' and 'hilbertCurve'): Defines whether the lower and upper boundary values of each parameter name shall be added as additional samples. If missing, defaults to FALSE. | +|    _iterationDepth | int | (optional, for sampling type 'hilbertCurve'): Defines the hilbert iteration depth, default: 10. | +|   _condition | dict | (optional) a condition allows to define a filter expression to include or exclude specific samples. (see [Filtering of Cases](#filtering-of-cases)) | +|    _filter | string | filter expression (see [Filter Expression](#filter-expression)) | +|    _action | string | (optional) defines the action triggered when the filter expression evaluates to True. Choices: 'include', 'exclude'. If missing, defaults to 'exclude'. (see [Action](#action)) | +|   _samples | dict | dict containing all samples. The '_samples' section of a layer is generated by farn when run with option --sample. | +|   _commands | dict | (optional) dict defining commandsets that can be executed in a layer. | +|    \ | list[string] | unique key defining a command element. A command element contains one or more shell commands, saved as a list of strings. When farn is called with -e \ argument, all shell commands listed in \ will be executed in the given sequence, in all case folders corresponding to the layer the command element is defined in. | + +## Example + +Below example shows a typical farnDict file. +In the example, a 6-dimensional design space is spawned, organised in 4 layers: +1. 'gp' level 0 (root layer) no. of parameters: 1 sampling: fixed (Example 'gp' indicating e.g. a hypothetical grid parameter) +2. 'lhsvar' level 1 (nested layer) no. of parameters: 3 sampling: uniformLhs (Example 3 dimensional sub design space, LHS sampled) +3. 'cp' level 2 (nested layer) no. of parameters: 1 sampling: linSpace (Example 'cp' indicating e.g. a hypothetical compute parameter (solver setting, version whatever)) +4. 'mp' level 3 (leaf layer) no. of parameters: 1 sampling: fixed (Example 'mp' indicating e.g. a hypothetical multiplier for an internal variable) +~~~js +/*---------------------------------*- C++ -*----------------------------------*\ +filetype dictionary; coding utf-8; version 0.1; local --; purpose --; +\*----------------------------------------------------------------------------*/ +_environment +{ + CASEDIR cases; + DUMPDIR dump; + LOGDIR logs; + RESULTDIR results; + TEMPLATEDIR template; +} +_always +{ + coeff_0 0.0; + coeff_1 10.0; +} +_layers +{ + gp // unique key defining a layer. Will be used by farn as basename for all case folders in the corresponding nest level. + { + _sampling + { + _type fixed; // Fixed values. Note: Each sampling type has its own set of required arguments. + _names(mpGrid); // list with names, each representing one variable or parameter. + _values((0.9 1.3)); // list containing list with fixed values, one list for each parameter name. Required for sampling type 'fixed'. + } + } + lhsvar + { + _sampling + { + _type uniformLhs; // Latin-Hypercube-Sampling. Future options might also include lognormlhs etc. (currently not implemented) + _names(param1 param2 param3); + _ranges((-10 10)(0 3.5)(0 1.1)); // list containing ranges. A range is defined through the lower and upper boundary value for the related parameter name, given as tuple (minimum, maximum). For each parameter name, one range tuple must exist. + _includeBoundingBox True; // [optional] defines whether the lower and upper boundary values of each parameter name shall be added as additional samples. If missing, defaults to False. + _numberOfSamples 100; // number of samples to be generated. The given number of samples will be generated within range (=between lower and upper boundary), excluding the boundaries themselves. + } + } + cp + { + _sampling + { + _type linSpace; // Linearly spaced sampling. + _names(relFactor); + _ranges((0.5 0.8)); + _numberOfSamples 5; + } + _condition // a condition allows to define a filter expression to include or exclude specific samples. + { + _filter 'param2 >= param3 and param1 >= 0'; // filter expression. + _action exclude; // [optional] defines the action triggered when the filter expression evaluates to True. choices: 'include', 'exclude'. If missing, defaults to 'exclude'. + } + } + hilbert + { + _sampling + { + _type hilbertCurve; // Hilbert-Sampling. (derived from Hilbert's space-filling curve for dimensions >= 2) + _names(param1 param2 param3); + _ranges((-5. 5.)(0. 10.)(-10 10.)); // A list, containing ranges. A range is defined through the lower and upper boundary value for the related parameter name, given as tuple (minimum, maximum). For each parameter name, one range tuple must exist. + _includeBoundingBox True; // [optional] defines whether the lower and upper boundary values of each parameter name shall be added as additional samples. It is not recommended to use this option in hilbert sampling because at least two samples will be coincident. + // If missing, defaults to False. If it is given, start and end points of Hilbert distribution coincide with bb points for technical reasons. + _numberOfSamples 20; // number of samples to be generated. The given number of samples will be generated within range (=between lower and upper boundary), excluding the boundaries themselves. Resampling, keeping the already done cases, is possible in a subsequent farn call by adding (_numberOfSamples-1) to itself. + // a new sampling iteration on the same data set should be done using _numberOfSamples_n+1 = _numberOfSamples_n + _numberOfSamples_n - 1 to retain the lowest possible correlations between samples. + _iterationDepth 5; // iteration depth of Hilbert's algorithm: this example generates 2**(3*5) = 32768 Hilbert points (H. length). + } + } + mp + { + _sampling + { + _type fixed; + _names(cpMul ppMul); // (just exemplary parameter names. Imagine e.g. be multipliers for solver and postprocessing.) + _values((1.5 2.0 3.5)(1.5 2.0 3.5)); + } + _commands // commands. Each element contains a list with one or more shell commands. + { + prepare // command 'prepare' (contains 3 shell commands) + ( + 'copy %TEMPLATEDIR%/caseDict' // shell command 1 + 'rem parsed.caseDict' // shell command 2 + 'dictParser --quiet caseDict' // shell command 3 + ); + run // command 'run' (contains 1 shell command) + ( + 'cosim.exe run OspSystemStructure.xml -b 0 -d 20 --real-time -v' + ); + } + } +} +~~~ + +## Filtering of Cases + +Filtering of cases is possible using the '_condition' element. The _condition element is evaluated with every call to farn, regardless of whether farn is run with option --sample, --generate or --execute. (However, still the _effect_ of filtering is different, depending on the option farn is called with. See [Effect of farn options on Filtering](#effect-of-farn-options-on-filtering)) + +The structure of the _condition element is as follows: +### Structure of the _condition Element + +~~~js +_condition +{ + _filter FILTER_EXPRESSION; + _action VALUE; +} +~~~ +Any _condition element must contain exactly one _filter expression and can optionally contain an _action value. +The _condition element is layer specific, meaning it must be defined inside a _layer element. Each _layer can contain maximum one _condition element (either no or one). + +### Filter Expression +The value of the _filter element is expected to be a string formatted expression containing a relational statement or list comparison. +Valid examples are e.g.: +| Filter Expression | Comment | +| :-----------------------------------------| :---------------------------- | +| `"param1 > 3"` | with param1 being a user defined key within the current scope (layer) | +| `"param1 < 0 or param2 == 1"` | with param1 & param2 being keys within current level combined with boolean expressions "and, "or" and "not" | +| `"param1 * sqrt(param2)"` | with param1 & param2 being keys within current level in combination with mathematical operators and constants | +| `"param1 not in [4, 5, 7]"` | with param1 list comparison | +| `"CASE_ATTRIBUTE in ['case_00', case_01']"` | with CASE_ATTRIBUTE being one of the case attributes made available by farn during runtime (see [Case Attributes](#case-attributes) below) | + +or any combination of the above. + +### Action +The optional _action element defines the action triggered in case the filter expression evaluates to True. + +Currently supported values are the string literals +* 'include' and +* 'exclude'. + +If the _action element is missing, action defaults to 'exclude'. + +farn evaluates the _filter expression and the _action value for each case and with every run of farn. + +
+ +A case is considered _valid_ if one of the following two conditions is met: +| | | +| --------------------------------------------------------------------------- | --------------------------------------------------- | +| _action is 'exclude' (default) and _filter expression evaluates to False | -> case is considered valid and will be included | +| _action is 'include' and _filter expression evaluates to True | -> case is considered valid and will be included | + +
+ +Correspondingly, a case is considered _invalid_ if either of the two complementing conditions is met: +| | | +| --------------------------------------------------------------------------- | --------------------------------------------------- | +| _action is 'exclude' (default) and _filter expression evaluates to True | -> case is considered invalid and will be excluded | +| _action is 'include' and _filter expression evaluates to False | -> case is considered invalid and will be excluded | + +### Case Attributes +The following case attributes can be used in filter expressions. They are made available as variables by farn during runtime. +| Case Attribute | Description | +| ------------------------- | ----------------------------------------------- | +| `case` | Name of the case | +| `layer` | Name of the layer | +| `level` | Level (integer, zero-based) | +| `index` | Index (integer, zero-based) | +| `path` | case folder path | +| `is_leaf` | Indication whether or not a case is a leaf case (bool) | + + + + +If unsure, elevate farn's log-level from INFO to DEBUG to see a list of available attributes for each processsed case.
+ +The benefit of this approach is that it allows to use filtering in order to e.g. process small chunks of specific cases, simply by adapting a filter expression in the sampled.farnDict file. This can come handy when i.e. drilling down on "problem" cases, see following example: +~~~js +_condition +{ + _filter "index in [0, 200, 201]"; + _action exclude; +} +~~~ + +### Effect of farn options on Filtering +It is important to note that, depending on the commandline option farn is called with, filtering results in different effects: +| farn option | Effect on Filtering | +| :------------------------------- | --------------------------------------------------- | +| `--sample` | cases will appear or disappear in the _samples section in sampled.farnDict file written by farn
(meaning the corresponding cases are either available or not available right from the start) | +| `--generate` | case folders will be generated or not | +| `--execute` | cases will be executed or not | + +Filter expressions in the sampled.farnDict file can be modified as needed, at any time, when working with farn. + +If, though, farn is called with --execute option and the folder of a case to be executed does actually not exist, farn will log a warning, mentioning that the respective case folder does not exist and needs to be generated first. +This most commonly happens when a filter expression got changed in between _generating_ the case folder structure and _executing_ command sets therein. +If so, simply generate the missing cases by calling farn with option --generate once again and then retry to execute the command set with option --execute. + +### Erraneous filter expressions +If a filter expression can not successfully be evaluated by farn, i.e. because parameter names are being used in the filter expression which are not (yet) defined or accesible in the current scope (layer), a warning is logged and the case is considered invalid. diff --git a/_sources/fileFormat.rst.txt b/_sources/fileFormat.rst.txt new file mode 100644 index 00000000..a4234edf --- /dev/null +++ b/_sources/fileFormat.rst.txt @@ -0,0 +1,9 @@ +File Formats +============ + +.. toctree:: + :maxdepth: 4 + + fileFormat.sub.farn + fileFormat.sub.ospx + fileFormat.sub.dictIO diff --git a/_sources/fileFormat.sDict.md.txt b/_sources/fileFormat.sDict.md.txt new file mode 100644 index 00000000..a39a31ca --- /dev/null +++ b/_sources/fileFormat.sDict.md.txt @@ -0,0 +1,281 @@ +# dict + +## Description + +The native file format used by dictIO shares, by intention, some commonalities with the [OpenFOAM](https://www.openfoam.com/documentation/guides/latest/doc/openfoam-guide-input-types.html) file format, but is kept simpler and more tolerant to different flavours of string formatting. + +## Structure + +The basic structure of a dict file consists of +* header (block comment) [optional] +* include directive(s) [optional] +* key'd elements (each written as key value pair) + +As header and include directives are optional, in its simplest form a dict file can contain just a single key'd element: +~~~cpp +var1 3.14159; +~~~ + +## Header + +The default block comment used as header in dict files generated by dictIO looks as follows: +~~~cpp +/*---------------------------------*- C++ -*----------------------------------*\ +filetype dictionary; coding utf-8; version 0.1; local --; purpose --; +\*----------------------------------------------------------------------------*/ +~~~ + +## #include Directive(s) + +One of the most powerful features of dict files is their ability to be cascaded through the use of #include directives. +An #include directive declares a (child) dict file to be merged into the (parent) dict when reading. + +This allows to separate i.e. a case agnostic configuration file from its case specific parameterization: +While the core configuration dict is kept unchanged, case specific parameterization is accomplished by varying only the parameter dict. + +An #include directive consists of the #include statement followed by the path to the dict to be included: +~~~cpp +#include 'a_paramDict_in_same_folder' +#include 'subfolder/a_paramDict_in_subfolder' // Posix style with forward slashes is recommended (will work also on Windows) +#include '../a_paramDict_in_parent_folder' +#include 'subfolder\a_paramDict_in_subfolder' // also ok, but not recommended +#include '..\a_paramDict_in_parent_folder' +~~~ + + +## Element Types + +The following element types are supported in dict files read and written by dictIO. +The table also indicates to which Python data type they are casted when a dict file is read. + +| element type | example | (Python type) | +| :------------ | :-------------------------------- | :---------------- | +| boolean | true, false, on, off | bool | +| number | 1, 1.0 | int, float | +| none | None, none, NULL, null | None | +| string | aString, 'a string', "a string" | str | +| dict | {key1 value1; key2 value2;} | dict | +| list | (1.0 2.0 3.0) | list | +| reference | $var1 | (type of var1) | +| expression | "$var1 + 4" | (type of var1) | + +## Examples + +Below examples demonstrate the different element types supported by dictIO in dict files. + +### booleans + +~~~cpp + bool1 true; // True + bool2 false; // False + bool3 True; // True + bool4 False; // False + bool5 on; // True + bool6 off; // False + bool7 ON; // True + bool8 OFF; // False +~~~ + +### numbers + +~~~cpp +int1 0; // int +int2 120; // int +float1 3.5; // float +float2 1.00000000e+00; // float +~~~ + +### nones + +~~~cpp +none1 None; // None +none2 none; // None +none3 NULL; // None +none4 null; // None +~~~ + +### strings + +~~~js +string1 ''; +string2 'string'; +string3 'string with spaces'; +string4 singleWordsWithoutSpacesCanAlsoBeDeclaredWithoutQuotes; +string5 'string with single quotes'; +string6 "string with double quotes"; +~~~ + +### dicts + +~~~js +emptyDict +{ + +} + +dictWithNumbers +{ + var1 1; + var2 2.0; + var3 3.14; +} + +dictWithStrings +{ + string1 'string1'; + string2 'string2 has spaces'; + string3 'string3'; + string4 'string4 is ok but note that string5 is empty'; + string5 ''; +} +~~~ + +### lists + +~~~js +emptyList +( + +); + +listWithNumbers +( + 1 2.0 3.14 +); + +matrix // a matrix is represented by a list of lists +( + (11 12 13) + (21 22 23) + (31 32 33) +); + + +listWithStrings +( + 'string1' 'string2 has spaces' 'string3' 'string4 is ok but note that string5 is empty' '' +); +~~~ + +## References and Expressions + +Any key'd element in a dict file can also be treated as a variable that can be pointed to using references. +A reference is denoted by a \$ character followed by the key of the element being referenced, also known as $keyword syntax. + +References, in turn, can be used inside expressions. Expressions are double-quoted strings containing +a mathematical expression where at least one operand is a reference. + +Below code listing demonstrates the use of references and expressions: + +~~~cpp +varA 1.0; +varB 2.0; +list (1.0 2.0 3.0); +matrix +( + (11 12 13) + (21 22 23) + (31 32 33) +); + +reference1 $varA; // simple reference to a variable. References are prefixed with $. +reference2 $list[0]; // indexed reference to an item in a list. +reference3 $matrix[0]; // indexed reference to a specific row in a matrix (=returns a list). +reference4 $matrix[0][1]; // indexed reference to a specific value in a matrix. +expression1 "$varA"; // expression. However, result of this expression is same as using a simple reference without double quotes. +expression2 "$varA + 4"; // expression with one reference and one constant. +expression3 "$varA + $varB"; // expression with two references. +expression4 "$list[0] + 3.14"; // expression with an indexed reference. +~~~ + + +## Nesting + +Both dicts and lists can be nested. +In fact, dicts and lists in a dict file can be arbitrarily nested. + +While lexically possible, readability of nested data structures quickly suffers. In dict files intended to be read and edited by humans, such as configuration files, nesting should hence be used carefully and reasonably limited (an example that commonly causes misinterpretation is where a dict is nested inside a list, see section [The dict-in-a-list Pitfall](#the-dict-in-a-list-pitfall) further below). + +From a pure lexical / technical point of view, though, complex nesting of dicts and lists is possible. So, in cases where dict files are written and read purely by machines, this can provide additional capabilities. + +~~~cpp +nesting +{ + emptyNestedDict + { + + } + emptyNestedList + ( + + ); + nestedDictWithNestedList + { + list1 + ( + 1.00000000e+00 2.20972831e-17 3.15717747e-18 + ); + list2 + ( + 2.20972831e-17 1.00000000e+00 -7.07290050e-18 + ); + list3 + ( + 3.15717747e-18 -7.07290050e-18 1.00000000e+00 + ); + } + nestedListWithNestedList + ( + ( + 1.00000000e+00 2.20972831e-17 3.15717747e-18 + ) + ( + 2.20972831e-17 1.00000000e+00 -7.07290050e-18 + ) + ( + 3.15717747e-18 -7.07290050e-18 1.00000000e+00 + ) + ); + nestedListWithNestedDict + ( + ( + 11 12 13 + ) + { + value21 21; + value22 22; + value23 23; + } + ( + 31 32 33 + ) + ); +} +~~~ + +## The dict-in-a-list Pitfall + +A very prominent example where nesting of dicts and lists deteriorates human readibility and causes misinterpretation is where a dict is nested inside a list. +Read below example to see why: + +~~~cpp +keyToADict // This is a key. You can access its value (the subsequent dict {}) as a key'd element -> myDict['keyToADict'] +{ // This is the key'd element associated with key 'keyToADict'. It is of type dict. + keyToAList // This is a key. You can access its value (the subsequent list ()) as a key'd element -> myDict['keyToADict']['keyToAList'] + ( // This is the key'd element associated with key 'keyToAList'. It is of type list. + notAKey // This is NOT a key. It is a list element of type string. You can access it by its index -> myDict['keyToADict']['keyToAList'][0] + { // This is NOT a key'd element. It is a list element of type dict. You can access it by its index -> myDict['keyToADict']['keyToAList'][1] + key1 value1; // This is a key'd element inside the surrounding dict -> myDict['keyToADict']['keyToAList'][1]['key1'] + key2 value2; // This is a key'd element inside the surrounding dict -> myDict['keyToADict']['keyToAList'][1]['key2'] + } + notAKey // another list element -> myDict['keyToADict']['keyToAList'][2] + notAKey // yet another list element -> myDict['keyToADict']['keyToAList'][3] + notAKey // yet .. well, you got the point .. -> myDict['keyToADict']['keyToAList'][4] + notAKey // NOT A KEY !! -> myDict['keyToADict']['keyToAList'][5] + { // another list element of type dict -> myDict['keyToADict']['keyToAList'][6] + key1 value1; // This is a key'd element inside the surrounding dict -> myDict['keyToADict']['keyToAList'][6]['key1'] + key2 value2; // This is a key'd element inside the surrounding dict -> myDict['keyToADict']['keyToAList'][6]['key2'] + } + ); +} +~~~ diff --git a/_sources/fileFormat.sub.dictIO.rst.txt b/_sources/fileFormat.sub.dictIO.rst.txt new file mode 100644 index 00000000..39400011 --- /dev/null +++ b/_sources/fileFormat.sub.dictIO.rst.txt @@ -0,0 +1,7 @@ +dictIO +------ + +.. toctree:: + :maxdepth: 3 + + fileFormat.sDict diff --git a/_sources/fileFormat.sub.farn.rst.txt b/_sources/fileFormat.sub.farn.rst.txt new file mode 100644 index 00000000..a0ae4ff5 --- /dev/null +++ b/_sources/fileFormat.sub.farn.rst.txt @@ -0,0 +1,7 @@ +farn +---- + +.. toctree:: + :maxdepth: 3 + + fileFormat.farnDict diff --git a/_sources/fileFormat.sub.ospx.rst.txt b/_sources/fileFormat.sub.ospx.rst.txt new file mode 100644 index 00000000..72577a64 --- /dev/null +++ b/_sources/fileFormat.sub.ospx.rst.txt @@ -0,0 +1,8 @@ +ospx +---- + +.. toctree:: + :maxdepth: 3 + + fileFormat.caseDict + fileFormat.watchDict diff --git a/_sources/fileFormat.watchDict.md.txt b/_sources/fileFormat.watchDict.md.txt new file mode 100644 index 00000000..28d7d328 --- /dev/null +++ b/_sources/fileFormat.watchDict.md.txt @@ -0,0 +1,61 @@ +# watchDict + +## Description + +A watchDict is a file in dictIO dict file format used with watchCosim. + +Normally there is no need to write a watchDict manually. +The watchDict file is created by opsCaseBuilder during its build process. This default watchDict file already covers all information from the involved fmu's. +However, where needed in advanced cases you can certainly reduce or adjust the automatically generated watchDict afterwards manually (or by a user defined tool / process). + +The watchDict file serves as configuration for watchCosim, allowing to +* monitor the progress of a running cosim simulation +* show a self defined convergence plot on the screen and save the image +* write a statistical summary of the results (as defined in watchDict and as far as the simulation has progressed). + + +## Elements + +| element / key | type | Description | +| :-------------------- | :-------- | :---------- | +| datasources | dict | {all, any, none} names of the involved fmu's | +|  \ | dict | key matching the name of an FMU to be monitored (without file extension) | +|   timeColumn | int | time axis (one column from \_DATETIME.csv (free-of-choice) | +|   dataColumns | list[int] | ordinate (columns from \_DATETIME.csv (sub-setting and ordering is free-of-choice) | +| delimiter | string | the type of delimiter in \_DATETIME.csv | +| simulation | dict | additional information about the monitored simulaton. Used for window decoration. | +|  name | string | name of the monitored simulation | + +## Related files +* ./watchDict +* results/resultDict +* results/dataFrame.dump +* results/SIMULATIONNAME.png + +## Example + +![convergence plot example](demoCase.png) + +Below example shows a typical watchDict file. + +~~~cpp +/*---------------------------------*- C++ -*----------------------------------*\ +filetype dictionary; coding utf-8; version 0.1; local --; purpose --; +\*----------------------------------------------------------------------------*/ +datasources +{ + myfmu + { + timeColumn 0; + dataColumns + ( + 1 2 3 4 + ); + } +} +delimiter ,; +simulation +{ + name demoCase; +} +~~~ diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt new file mode 100644 index 00000000..e0eb495f --- /dev/null +++ b/_sources/index.rst.txt @@ -0,0 +1,26 @@ +.. combined documentation master file + +farn Documentation +================== + +.. toctree:: + :maxdepth: 5 + :caption: Contents: + + README_farn + README_ospx + README_dictIO + changelogs + LICENSE + api + cli + fileFormat + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/_sources/ospx.rst.txt b/_sources/ospx.rst.txt new file mode 100644 index 00000000..2f507738 --- /dev/null +++ b/_sources/ospx.rst.txt @@ -0,0 +1,33 @@ +ospx package +============ + +Subpackages +----------- + +.. autosummary:: + :toctree: _autosummary + :template: custom-module.rst + :recursive: + + ospx.fmi + ospx.watch + ospx.utils + + +Modules +------- + +.. autosummary:: + :toctree: _autosummary + :template: custom-module.rst + :recursive: + + ospx.component + ospx.connection + ospx.connector + ospx.graph + ospx.importer + ospx.ospCaseBuilder + ospx.ospSimulationCase + ospx.simulation + ospx.system diff --git a/_static/OSPx.png b/_static/OSPx.png new file mode 100644 index 00000000..18e206f7 Binary files /dev/null and b/_static/OSPx.png differ diff --git a/_static/OSPx.svg b/_static/OSPx.svg new file mode 100644 index 00000000..49428596 --- /dev/null +++ b/_static/OSPx.svg @@ -0,0 +1 @@ +ospxOSP \ No newline at end of file diff --git a/_static/basic.css b/_static/basic.css new file mode 100644 index 00000000..7ebbd6d0 --- /dev/null +++ b/_static/basic.css @@ -0,0 +1,914 @@ +/* + * Sphinx stylesheet -- basic theme. + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin-top: 10px; +} + +ul.search li { + padding: 5px 0; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/_static/debug.css b/_static/debug.css new file mode 100644 index 00000000..74d4aec3 --- /dev/null +++ b/_static/debug.css @@ -0,0 +1,69 @@ +/* + This CSS file should be overridden by the theme authors. It's + meant for debugging and developing the skeleton that this theme provides. +*/ +body { + font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, + "Apple Color Emoji", "Segoe UI Emoji"; + background: lavender; +} +.sb-announcement { + background: rgb(131, 131, 131); +} +.sb-announcement__inner { + background: black; + color: white; +} +.sb-header { + background: lightskyblue; +} +.sb-header__inner { + background: royalblue; + color: white; +} +.sb-header-secondary { + background: lightcyan; +} +.sb-header-secondary__inner { + background: cornflowerblue; + color: white; +} +.sb-sidebar-primary { + background: lightgreen; +} +.sb-main { + background: blanchedalmond; +} +.sb-main__inner { + background: antiquewhite; +} +.sb-header-article { + background: lightsteelblue; +} +.sb-article-container { + background: snow; +} +.sb-article-main { + background: white; +} +.sb-footer-article { + background: lightpink; +} +.sb-sidebar-secondary { + background: lightgoldenrodyellow; +} +.sb-footer-content { + background: plum; +} +.sb-footer-content__inner { + background: palevioletred; +} +.sb-footer { + background: pink; +} +.sb-footer__inner { + background: salmon; +} +.sb-article { + background: white; +} diff --git a/_static/dictIO.png b/_static/dictIO.png new file mode 100644 index 00000000..0e7d683a Binary files /dev/null and b/_static/dictIO.png differ diff --git a/_static/dictIO.svg b/_static/dictIO.svg new file mode 100644 index 00000000..367cb4de --- /dev/null +++ b/_static/dictIO.svg @@ -0,0 +1 @@ +dictIOOSP \ No newline at end of file diff --git a/_static/doctools.js b/_static/doctools.js new file mode 100644 index 00000000..0398ebb9 --- /dev/null +++ b/_static/doctools.js @@ -0,0 +1,149 @@ +/* + * Base JavaScript utilities for all Sphinx HTML documentation. + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/_static/documentation_options.js b/_static/documentation_options.js new file mode 100644 index 00000000..025330ce --- /dev/null +++ b/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '0.4.0', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/_static/farn.png b/_static/farn.png new file mode 100644 index 00000000..34671315 Binary files /dev/null and b/_static/farn.png differ diff --git a/_static/farn.svg b/_static/farn.svg new file mode 100644 index 00000000..4ad5b8fa --- /dev/null +++ b/_static/farn.svg @@ -0,0 +1 @@ +farnOSP \ No newline at end of file diff --git a/_static/file.png b/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/_static/file.png differ diff --git a/_static/language_data.js b/_static/language_data.js new file mode 100644 index 00000000..c7fe6c6f --- /dev/null +++ b/_static/language_data.js @@ -0,0 +1,192 @@ +/* + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, if available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/_static/minus.png b/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/_static/minus.png differ diff --git a/_static/plot_directive.css b/_static/plot_directive.css new file mode 100644 index 00000000..d45593c9 --- /dev/null +++ b/_static/plot_directive.css @@ -0,0 +1,16 @@ +/* + * plot_directive.css + * ~~~~~~~~~~~~ + * + * Stylesheet controlling images created using the `plot` directive within + * Sphinx. + * + * :copyright: Copyright 2020-* by the Matplotlib development team. + * :license: Matplotlib, see LICENSE for details. + * + */ + +img.plot-directive { + border: 0; + max-width: 100%; +} diff --git a/_static/plus.png b/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/_static/plus.png differ diff --git a/_static/pygments.css b/_static/pygments.css new file mode 100644 index 00000000..02b4b128 --- /dev/null +++ b/_static/pygments.css @@ -0,0 +1,258 @@ +.highlight pre { line-height: 125%; } +.highlight td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +.highlight span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +.highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f8f8f8; } +.highlight .c { color: #8f5902; font-style: italic } /* Comment */ +.highlight .err { color: #a40000; border: 1px solid #ef2929 } /* Error */ +.highlight .g { color: #000000 } /* Generic */ +.highlight .k { color: #204a87; font-weight: bold } /* Keyword */ +.highlight .l { color: #000000 } /* Literal */ +.highlight .n { color: #000000 } /* Name */ +.highlight .o { color: #ce5c00; font-weight: bold } /* Operator */ +.highlight .x { color: #000000 } /* Other */ +.highlight .p { color: #000000; font-weight: bold } /* Punctuation */ +.highlight .ch { color: #8f5902; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #8f5902; font-style: italic } /* Comment.Preproc */ +.highlight .cpf { color: #8f5902; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #8f5902; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #a40000 } /* Generic.Deleted */ +.highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */ +.highlight .ges { color: #000000; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #ef2929 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #000000; font-style: italic } /* Generic.Output */ +.highlight .gp { color: #8f5902 } /* Generic.Prompt */ +.highlight .gs { color: #000000; font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */ +.highlight .kc { color: #204a87; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #204a87; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #204a87; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #204a87; font-weight: bold } /* Keyword.Pseudo */ +.highlight .kr { color: #204a87; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #204a87; font-weight: bold } /* Keyword.Type */ +.highlight .ld { color: #000000 } /* Literal.Date */ +.highlight .m { color: #0000cf; font-weight: bold } /* Literal.Number */ +.highlight .s { color: #4e9a06 } /* Literal.String */ +.highlight .na { color: #c4a000 } /* Name.Attribute */ +.highlight .nb { color: #204a87 } /* Name.Builtin */ +.highlight .nc { color: #000000 } /* Name.Class */ +.highlight .no { color: #000000 } /* Name.Constant */ +.highlight .nd { color: #5c35cc; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #ce5c00 } /* Name.Entity */ +.highlight .ne { color: #cc0000; font-weight: bold } /* Name.Exception */ +.highlight .nf { color: #000000 } /* Name.Function */ +.highlight .nl { color: #f57900 } /* Name.Label */ +.highlight .nn { color: #000000 } /* Name.Namespace */ +.highlight .nx { color: #000000 } /* Name.Other */ +.highlight .py { color: #000000 } /* Name.Property */ +.highlight .nt { color: #204a87; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #000000 } /* Name.Variable */ +.highlight .ow { color: #204a87; font-weight: bold } /* Operator.Word */ +.highlight .pm { color: #000000; font-weight: bold } /* Punctuation.Marker */ +.highlight .w { color: #f8f8f8 } /* Text.Whitespace */ +.highlight .mb { color: #0000cf; font-weight: bold } /* Literal.Number.Bin */ +.highlight .mf { color: #0000cf; font-weight: bold } /* Literal.Number.Float */ +.highlight .mh { color: #0000cf; font-weight: bold } /* Literal.Number.Hex */ +.highlight .mi { color: #0000cf; font-weight: bold } /* Literal.Number.Integer */ +.highlight .mo { color: #0000cf; font-weight: bold } /* Literal.Number.Oct */ +.highlight .sa { color: #4e9a06 } /* Literal.String.Affix */ +.highlight .sb { color: #4e9a06 } /* Literal.String.Backtick */ +.highlight .sc { color: #4e9a06 } /* Literal.String.Char */ +.highlight .dl { color: #4e9a06 } /* Literal.String.Delimiter */ +.highlight .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4e9a06 } /* Literal.String.Double */ +.highlight .se { color: #4e9a06 } /* Literal.String.Escape */ +.highlight .sh { color: #4e9a06 } /* Literal.String.Heredoc */ +.highlight .si { color: #4e9a06 } /* Literal.String.Interpol */ +.highlight .sx { color: #4e9a06 } /* Literal.String.Other */ +.highlight .sr { color: #4e9a06 } /* Literal.String.Regex */ +.highlight .s1 { color: #4e9a06 } /* Literal.String.Single */ +.highlight .ss { color: #4e9a06 } /* Literal.String.Symbol */ +.highlight .bp { color: #3465a4 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #000000 } /* Name.Function.Magic */ +.highlight .vc { color: #000000 } /* Name.Variable.Class */ +.highlight .vg { color: #000000 } /* Name.Variable.Global */ +.highlight .vi { color: #000000 } /* Name.Variable.Instance */ +.highlight .vm { color: #000000 } /* Name.Variable.Magic */ +.highlight .il { color: #0000cf; font-weight: bold } /* Literal.Number.Integer.Long */ +@media not print { +body[data-theme="dark"] .highlight pre { line-height: 125%; } +body[data-theme="dark"] .highlight td.linenos .normal { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight span.linenos { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight .hll { background-color: #404040 } +body[data-theme="dark"] .highlight { background: #202020; color: #d0d0d0 } +body[data-theme="dark"] .highlight .c { color: #ababab; font-style: italic } /* Comment */ +body[data-theme="dark"] .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ +body[data-theme="dark"] .highlight .esc { color: #d0d0d0 } /* Escape */ +body[data-theme="dark"] .highlight .g { color: #d0d0d0 } /* Generic */ +body[data-theme="dark"] .highlight .k { color: #6ebf26; font-weight: bold } /* Keyword */ +body[data-theme="dark"] .highlight .l { color: #d0d0d0 } /* Literal */ +body[data-theme="dark"] .highlight .n { color: #d0d0d0 } /* Name */ +body[data-theme="dark"] .highlight .o { color: #d0d0d0 } /* Operator */ +body[data-theme="dark"] .highlight .x { color: #d0d0d0 } /* Other */ +body[data-theme="dark"] .highlight .p { color: #d0d0d0 } /* Punctuation */ +body[data-theme="dark"] .highlight .ch { color: #ababab; font-style: italic } /* Comment.Hashbang */ +body[data-theme="dark"] .highlight .cm { color: #ababab; font-style: italic } /* Comment.Multiline */ +body[data-theme="dark"] .highlight .cp { color: #ff3a3a; font-weight: bold } /* Comment.Preproc */ +body[data-theme="dark"] .highlight .cpf { color: #ababab; font-style: italic } /* Comment.PreprocFile */ +body[data-theme="dark"] .highlight .c1 { color: #ababab; font-style: italic } /* Comment.Single */ +body[data-theme="dark"] .highlight .cs { color: #e50808; font-weight: bold; background-color: #520000 } /* Comment.Special */ +body[data-theme="dark"] .highlight .gd { color: #ff3a3a } /* Generic.Deleted */ +body[data-theme="dark"] .highlight .ge { color: #d0d0d0; font-style: italic } /* Generic.Emph */ +body[data-theme="dark"] .highlight .ges { color: #d0d0d0; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +body[data-theme="dark"] .highlight .gr { color: #ff3a3a } /* Generic.Error */ +body[data-theme="dark"] .highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */ +body[data-theme="dark"] .highlight .gi { color: #589819 } /* Generic.Inserted */ +body[data-theme="dark"] .highlight .go { color: #cccccc } /* Generic.Output */ +body[data-theme="dark"] .highlight .gp { color: #aaaaaa } /* Generic.Prompt */ +body[data-theme="dark"] .highlight .gs { color: #d0d0d0; font-weight: bold } /* Generic.Strong */ +body[data-theme="dark"] .highlight .gu { color: #ffffff; text-decoration: underline } /* Generic.Subheading */ +body[data-theme="dark"] .highlight .gt { color: #ff3a3a } /* Generic.Traceback */ +body[data-theme="dark"] .highlight .kc { color: #6ebf26; font-weight: bold } /* Keyword.Constant */ +body[data-theme="dark"] .highlight .kd { color: #6ebf26; font-weight: bold } /* Keyword.Declaration */ +body[data-theme="dark"] .highlight .kn { color: #6ebf26; font-weight: bold } /* Keyword.Namespace */ +body[data-theme="dark"] .highlight .kp { color: #6ebf26 } /* Keyword.Pseudo */ +body[data-theme="dark"] .highlight .kr { color: #6ebf26; font-weight: bold } /* Keyword.Reserved */ +body[data-theme="dark"] .highlight .kt { color: #6ebf26; font-weight: bold } /* Keyword.Type */ +body[data-theme="dark"] .highlight .ld { color: #d0d0d0 } /* Literal.Date */ +body[data-theme="dark"] .highlight .m { color: #51b2fd } /* Literal.Number */ +body[data-theme="dark"] .highlight .s { color: #ed9d13 } /* Literal.String */ +body[data-theme="dark"] .highlight .na { color: #bbbbbb } /* Name.Attribute */ +body[data-theme="dark"] .highlight .nb { color: #2fbccd } /* Name.Builtin */ +body[data-theme="dark"] .highlight .nc { color: #71adff; text-decoration: underline } /* Name.Class */ +body[data-theme="dark"] .highlight .no { color: #40ffff } /* Name.Constant */ +body[data-theme="dark"] .highlight .nd { color: #ffa500 } /* Name.Decorator */ +body[data-theme="dark"] .highlight .ni { color: #d0d0d0 } /* Name.Entity */ +body[data-theme="dark"] .highlight .ne { color: #bbbbbb } /* Name.Exception */ +body[data-theme="dark"] .highlight .nf { color: #71adff } /* Name.Function */ +body[data-theme="dark"] .highlight .nl { color: #d0d0d0 } /* Name.Label */ +body[data-theme="dark"] .highlight .nn { color: #71adff; text-decoration: underline } /* Name.Namespace */ +body[data-theme="dark"] .highlight .nx { color: #d0d0d0 } /* Name.Other */ +body[data-theme="dark"] .highlight .py { color: #d0d0d0 } /* Name.Property */ +body[data-theme="dark"] .highlight .nt { color: #6ebf26; font-weight: bold } /* Name.Tag */ +body[data-theme="dark"] .highlight .nv { color: #40ffff } /* Name.Variable */ +body[data-theme="dark"] .highlight .ow { color: #6ebf26; font-weight: bold } /* Operator.Word */ +body[data-theme="dark"] .highlight .pm { color: #d0d0d0 } /* Punctuation.Marker */ +body[data-theme="dark"] .highlight .w { color: #666666 } /* Text.Whitespace */ +body[data-theme="dark"] .highlight .mb { color: #51b2fd } /* Literal.Number.Bin */ +body[data-theme="dark"] .highlight .mf { color: #51b2fd } /* Literal.Number.Float */ +body[data-theme="dark"] .highlight .mh { color: #51b2fd } /* Literal.Number.Hex */ +body[data-theme="dark"] .highlight .mi { color: #51b2fd } /* Literal.Number.Integer */ +body[data-theme="dark"] .highlight .mo { color: #51b2fd } /* Literal.Number.Oct */ +body[data-theme="dark"] .highlight .sa { color: #ed9d13 } /* Literal.String.Affix */ +body[data-theme="dark"] .highlight .sb { color: #ed9d13 } /* Literal.String.Backtick */ +body[data-theme="dark"] .highlight .sc { color: #ed9d13 } /* Literal.String.Char */ +body[data-theme="dark"] .highlight .dl { color: #ed9d13 } /* Literal.String.Delimiter */ +body[data-theme="dark"] .highlight .sd { color: #ed9d13 } /* Literal.String.Doc */ +body[data-theme="dark"] .highlight .s2 { color: #ed9d13 } /* Literal.String.Double */ +body[data-theme="dark"] .highlight .se { color: #ed9d13 } /* Literal.String.Escape */ +body[data-theme="dark"] .highlight .sh { color: #ed9d13 } /* Literal.String.Heredoc */ +body[data-theme="dark"] .highlight .si { color: #ed9d13 } /* Literal.String.Interpol */ +body[data-theme="dark"] .highlight .sx { color: #ffa500 } /* Literal.String.Other */ +body[data-theme="dark"] .highlight .sr { color: #ed9d13 } /* Literal.String.Regex */ +body[data-theme="dark"] .highlight .s1 { color: #ed9d13 } /* Literal.String.Single */ +body[data-theme="dark"] .highlight .ss { color: #ed9d13 } /* Literal.String.Symbol */ +body[data-theme="dark"] .highlight .bp { color: #2fbccd } /* Name.Builtin.Pseudo */ +body[data-theme="dark"] .highlight .fm { color: #71adff } /* Name.Function.Magic */ +body[data-theme="dark"] .highlight .vc { color: #40ffff } /* Name.Variable.Class */ +body[data-theme="dark"] .highlight .vg { color: #40ffff } /* Name.Variable.Global */ +body[data-theme="dark"] .highlight .vi { color: #40ffff } /* Name.Variable.Instance */ +body[data-theme="dark"] .highlight .vm { color: #40ffff } /* Name.Variable.Magic */ +body[data-theme="dark"] .highlight .il { color: #51b2fd } /* Literal.Number.Integer.Long */ +@media (prefers-color-scheme: dark) { +body:not([data-theme="light"]) .highlight pre { line-height: 125%; } +body:not([data-theme="light"]) .highlight td.linenos .normal { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight span.linenos { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight .hll { background-color: #404040 } +body:not([data-theme="light"]) .highlight { background: #202020; color: #d0d0d0 } +body:not([data-theme="light"]) .highlight .c { color: #ababab; font-style: italic } /* Comment */ +body:not([data-theme="light"]) .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ +body:not([data-theme="light"]) .highlight .esc { color: #d0d0d0 } /* Escape */ +body:not([data-theme="light"]) .highlight .g { color: #d0d0d0 } /* Generic */ +body:not([data-theme="light"]) .highlight .k { color: #6ebf26; font-weight: bold } /* Keyword */ +body:not([data-theme="light"]) .highlight .l { color: #d0d0d0 } /* Literal */ +body:not([data-theme="light"]) .highlight .n { color: #d0d0d0 } /* Name */ +body:not([data-theme="light"]) .highlight .o { color: #d0d0d0 } /* Operator */ +body:not([data-theme="light"]) .highlight .x { color: #d0d0d0 } /* Other */ +body:not([data-theme="light"]) .highlight .p { color: #d0d0d0 } /* Punctuation */ +body:not([data-theme="light"]) .highlight .ch { color: #ababab; font-style: italic } /* Comment.Hashbang */ +body:not([data-theme="light"]) .highlight .cm { color: #ababab; font-style: italic } /* Comment.Multiline */ +body:not([data-theme="light"]) .highlight .cp { color: #ff3a3a; font-weight: bold } /* Comment.Preproc */ +body:not([data-theme="light"]) .highlight .cpf { color: #ababab; font-style: italic } /* Comment.PreprocFile */ +body:not([data-theme="light"]) .highlight .c1 { color: #ababab; font-style: italic } /* Comment.Single */ +body:not([data-theme="light"]) .highlight .cs { color: #e50808; font-weight: bold; background-color: #520000 } /* Comment.Special */ +body:not([data-theme="light"]) .highlight .gd { color: #ff3a3a } /* Generic.Deleted */ +body:not([data-theme="light"]) .highlight .ge { color: #d0d0d0; font-style: italic } /* Generic.Emph */ +body:not([data-theme="light"]) .highlight .ges { color: #d0d0d0; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +body:not([data-theme="light"]) .highlight .gr { color: #ff3a3a } /* Generic.Error */ +body:not([data-theme="light"]) .highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */ +body:not([data-theme="light"]) .highlight .gi { color: #589819 } /* Generic.Inserted */ +body:not([data-theme="light"]) .highlight .go { color: #cccccc } /* Generic.Output */ +body:not([data-theme="light"]) .highlight .gp { color: #aaaaaa } /* Generic.Prompt */ +body:not([data-theme="light"]) .highlight .gs { color: #d0d0d0; font-weight: bold } /* Generic.Strong */ +body:not([data-theme="light"]) .highlight .gu { color: #ffffff; text-decoration: underline } /* Generic.Subheading */ +body:not([data-theme="light"]) .highlight .gt { color: #ff3a3a } /* Generic.Traceback */ +body:not([data-theme="light"]) .highlight .kc { color: #6ebf26; font-weight: bold } /* Keyword.Constant */ +body:not([data-theme="light"]) .highlight .kd { color: #6ebf26; font-weight: bold } /* Keyword.Declaration */ +body:not([data-theme="light"]) .highlight .kn { color: #6ebf26; font-weight: bold } /* Keyword.Namespace */ +body:not([data-theme="light"]) .highlight .kp { color: #6ebf26 } /* Keyword.Pseudo */ +body:not([data-theme="light"]) .highlight .kr { color: #6ebf26; font-weight: bold } /* Keyword.Reserved */ +body:not([data-theme="light"]) .highlight .kt { color: #6ebf26; font-weight: bold } /* Keyword.Type */ +body:not([data-theme="light"]) .highlight .ld { color: #d0d0d0 } /* Literal.Date */ +body:not([data-theme="light"]) .highlight .m { color: #51b2fd } /* Literal.Number */ +body:not([data-theme="light"]) .highlight .s { color: #ed9d13 } /* Literal.String */ +body:not([data-theme="light"]) .highlight .na { color: #bbbbbb } /* Name.Attribute */ +body:not([data-theme="light"]) .highlight .nb { color: #2fbccd } /* Name.Builtin */ +body:not([data-theme="light"]) .highlight .nc { color: #71adff; text-decoration: underline } /* Name.Class */ +body:not([data-theme="light"]) .highlight .no { color: #40ffff } /* Name.Constant */ +body:not([data-theme="light"]) .highlight .nd { color: #ffa500 } /* Name.Decorator */ +body:not([data-theme="light"]) .highlight .ni { color: #d0d0d0 } /* Name.Entity */ +body:not([data-theme="light"]) .highlight .ne { color: #bbbbbb } /* Name.Exception */ +body:not([data-theme="light"]) .highlight .nf { color: #71adff } /* Name.Function */ +body:not([data-theme="light"]) .highlight .nl { color: #d0d0d0 } /* Name.Label */ +body:not([data-theme="light"]) .highlight .nn { color: #71adff; text-decoration: underline } /* Name.Namespace */ +body:not([data-theme="light"]) .highlight .nx { color: #d0d0d0 } /* Name.Other */ +body:not([data-theme="light"]) .highlight .py { color: #d0d0d0 } /* Name.Property */ +body:not([data-theme="light"]) .highlight .nt { color: #6ebf26; font-weight: bold } /* Name.Tag */ +body:not([data-theme="light"]) .highlight .nv { color: #40ffff } /* Name.Variable */ +body:not([data-theme="light"]) .highlight .ow { color: #6ebf26; font-weight: bold } /* Operator.Word */ +body:not([data-theme="light"]) .highlight .pm { color: #d0d0d0 } /* Punctuation.Marker */ +body:not([data-theme="light"]) .highlight .w { color: #666666 } /* Text.Whitespace */ +body:not([data-theme="light"]) .highlight .mb { color: #51b2fd } /* Literal.Number.Bin */ +body:not([data-theme="light"]) .highlight .mf { color: #51b2fd } /* Literal.Number.Float */ +body:not([data-theme="light"]) .highlight .mh { color: #51b2fd } /* Literal.Number.Hex */ +body:not([data-theme="light"]) .highlight .mi { color: #51b2fd } /* Literal.Number.Integer */ +body:not([data-theme="light"]) .highlight .mo { color: #51b2fd } /* Literal.Number.Oct */ +body:not([data-theme="light"]) .highlight .sa { color: #ed9d13 } /* Literal.String.Affix */ +body:not([data-theme="light"]) .highlight .sb { color: #ed9d13 } /* Literal.String.Backtick */ +body:not([data-theme="light"]) .highlight .sc { color: #ed9d13 } /* Literal.String.Char */ +body:not([data-theme="light"]) .highlight .dl { color: #ed9d13 } /* Literal.String.Delimiter */ +body:not([data-theme="light"]) .highlight .sd { color: #ed9d13 } /* Literal.String.Doc */ +body:not([data-theme="light"]) .highlight .s2 { color: #ed9d13 } /* Literal.String.Double */ +body:not([data-theme="light"]) .highlight .se { color: #ed9d13 } /* Literal.String.Escape */ +body:not([data-theme="light"]) .highlight .sh { color: #ed9d13 } /* Literal.String.Heredoc */ +body:not([data-theme="light"]) .highlight .si { color: #ed9d13 } /* Literal.String.Interpol */ +body:not([data-theme="light"]) .highlight .sx { color: #ffa500 } /* Literal.String.Other */ +body:not([data-theme="light"]) .highlight .sr { color: #ed9d13 } /* Literal.String.Regex */ +body:not([data-theme="light"]) .highlight .s1 { color: #ed9d13 } /* Literal.String.Single */ +body:not([data-theme="light"]) .highlight .ss { color: #ed9d13 } /* Literal.String.Symbol */ +body:not([data-theme="light"]) .highlight .bp { color: #2fbccd } /* Name.Builtin.Pseudo */ +body:not([data-theme="light"]) .highlight .fm { color: #71adff } /* Name.Function.Magic */ +body:not([data-theme="light"]) .highlight .vc { color: #40ffff } /* Name.Variable.Class */ +body:not([data-theme="light"]) .highlight .vg { color: #40ffff } /* Name.Variable.Global */ +body:not([data-theme="light"]) .highlight .vi { color: #40ffff } /* Name.Variable.Instance */ +body:not([data-theme="light"]) .highlight .vm { color: #40ffff } /* Name.Variable.Magic */ +body:not([data-theme="light"]) .highlight .il { color: #51b2fd } /* Literal.Number.Integer.Long */ +} +} \ No newline at end of file diff --git a/_static/scripts/furo-extensions.js b/_static/scripts/furo-extensions.js new file mode 100644 index 00000000..e69de29b diff --git a/_static/scripts/furo.js b/_static/scripts/furo.js new file mode 100644 index 00000000..0abb2afa --- /dev/null +++ b/_static/scripts/furo.js @@ -0,0 +1,3 @@ +/*! For license information please see furo.js.LICENSE.txt */ +(()=>{var t={856:function(t,e,n){var o,r;r=void 0!==n.g?n.g:"undefined"!=typeof window?window:this,o=function(){return function(t){"use strict";var e={navClass:"active",contentClass:"active",nested:!1,nestedClass:"active",offset:0,reflow:!1,events:!0},n=function(t,e,n){if(n.settings.events){var o=new CustomEvent(t,{bubbles:!0,cancelable:!0,detail:n});e.dispatchEvent(o)}},o=function(t){var e=0;if(t.offsetParent)for(;t;)e+=t.offsetTop,t=t.offsetParent;return e>=0?e:0},r=function(t){t&&t.sort((function(t,e){return o(t.content)=Math.max(document.body.scrollHeight,document.documentElement.scrollHeight,document.body.offsetHeight,document.documentElement.offsetHeight,document.body.clientHeight,document.documentElement.clientHeight)},l=function(t,e){var n=t[t.length-1];if(function(t,e){return!(!s()||!c(t.content,e,!0))}(n,e))return n;for(var o=t.length-1;o>=0;o--)if(c(t[o].content,e))return t[o]},a=function(t,e){if(e.nested&&t.parentNode){var n=t.parentNode.closest("li");n&&(n.classList.remove(e.nestedClass),a(n,e))}},i=function(t,e){if(t){var o=t.nav.closest("li");o&&(o.classList.remove(e.navClass),t.content.classList.remove(e.contentClass),a(o,e),n("gumshoeDeactivate",o,{link:t.nav,content:t.content,settings:e}))}},u=function(t,e){if(e.nested){var n=t.parentNode.closest("li");n&&(n.classList.add(e.nestedClass),u(n,e))}};return function(o,c){var s,a,d,f,m,v={setup:function(){s=document.querySelectorAll(o),a=[],Array.prototype.forEach.call(s,(function(t){var e=document.getElementById(decodeURIComponent(t.hash.substr(1)));e&&a.push({nav:t,content:e})})),r(a)},detect:function(){var t=l(a,m);t?d&&t.content===d.content||(i(d,m),function(t,e){if(t){var o=t.nav.closest("li");o&&(o.classList.add(e.navClass),t.content.classList.add(e.contentClass),u(o,e),n("gumshoeActivate",o,{link:t.nav,content:t.content,settings:e}))}}(t,m),d=t):d&&(i(d,m),d=null)}},h=function(e){f&&t.cancelAnimationFrame(f),f=t.requestAnimationFrame(v.detect)},g=function(e){f&&t.cancelAnimationFrame(f),f=t.requestAnimationFrame((function(){r(a),v.detect()}))};return v.destroy=function(){d&&i(d,m),t.removeEventListener("scroll",h,!1),m.reflow&&t.removeEventListener("resize",g,!1),a=null,s=null,d=null,f=null,m=null},m=function(){var t={};return Array.prototype.forEach.call(arguments,(function(e){for(var n in e){if(!e.hasOwnProperty(n))return;t[n]=e[n]}})),t}(e,c||{}),v.setup(),v.detect(),t.addEventListener("scroll",h,!1),m.reflow&&t.addEventListener("resize",g,!1),v}}(r)}.apply(e,[]),void 0===o||(t.exports=o)}},e={};function n(o){var r=e[o];if(void 0!==r)return r.exports;var c=e[o]={exports:{}};return t[o].call(c.exports,c,c.exports,n),c.exports}n.n=t=>{var e=t&&t.__esModule?()=>t.default:()=>t;return n.d(e,{a:e}),e},n.d=(t,e)=>{for(var o in e)n.o(e,o)&&!n.o(t,o)&&Object.defineProperty(t,o,{enumerable:!0,get:e[o]})},n.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(t){if("object"==typeof window)return window}}(),n.o=(t,e)=>Object.prototype.hasOwnProperty.call(t,e),(()=>{"use strict";var t=n(856),e=n.n(t),o=null,r=null,c=document.documentElement.scrollTop;const s=64;function l(){const t=localStorage.getItem("theme")||"auto";var e;"light"!==(e=window.matchMedia("(prefers-color-scheme: dark)").matches?"auto"===t?"light":"light"==t?"dark":"auto":"auto"===t?"dark":"dark"==t?"light":"auto")&&"dark"!==e&&"auto"!==e&&(console.error(`Got invalid theme mode: ${e}. Resetting to auto.`),e="auto"),document.body.dataset.theme=e,localStorage.setItem("theme",e),console.log(`Changed to ${e} mode.`)}function a(){!function(){const t=document.getElementsByClassName("theme-toggle");Array.from(t).forEach((t=>{t.addEventListener("click",l)}))}(),function(){let t=0,e=!1;window.addEventListener("scroll",(function(n){t=window.scrollY,e||(window.requestAnimationFrame((function(){var n;(function(t){const e=Math.floor(r.getBoundingClientRect().top);console.log(`headerTop: ${e}`),0==e&&t!=e?r.classList.add("scrolled"):r.classList.remove("scrolled")})(n=t),function(t){tc&&document.documentElement.classList.remove("show-back-to-top"),c=t}(n),function(t){null!==o&&(0==t?o.scrollTo(0,0):Math.ceil(t)>=Math.floor(document.documentElement.scrollHeight-window.innerHeight)?o.scrollTo(0,o.scrollHeight):document.querySelector(".scroll-current"))}(n),e=!1})),e=!0)})),window.scroll()}(),null!==o&&new(e())(".toc-tree a",{reflow:!0,recursive:!0,navClass:"scroll-current",offset:()=>{let t=parseFloat(getComputedStyle(document.documentElement).fontSize);return r.getBoundingClientRect().height+2.5*t+1}})}document.addEventListener("DOMContentLoaded",(function(){document.body.parentNode.classList.remove("no-js"),r=document.querySelector("header"),o=document.querySelector(".toc-scroll"),a()}))})()})(); +//# sourceMappingURL=furo.js.map \ No newline at end of file diff --git a/_static/scripts/furo.js.LICENSE.txt b/_static/scripts/furo.js.LICENSE.txt new file mode 100644 index 00000000..1632189c --- /dev/null +++ b/_static/scripts/furo.js.LICENSE.txt @@ -0,0 +1,7 @@ +/*! + * gumshoejs v5.1.2 (patched by @pradyunsg) + * A simple, framework-agnostic scrollspy script. + * (c) 2019 Chris Ferdinandi + * MIT License + * http://github.com/cferdinandi/gumshoe + */ diff --git a/_static/scripts/furo.js.map b/_static/scripts/furo.js.map new file mode 100644 index 00000000..80ea12b8 --- /dev/null +++ b/_static/scripts/furo.js.map @@ -0,0 +1 @@ +{"version":3,"file":"scripts/furo.js","mappings":";iCAAA,MAQWA,SAWS,IAAX,EAAAC,EACH,EAAAA,EACkB,oBAAXC,OACLA,OACAC,KAbO,EAAF,WACP,OAaJ,SAAUD,GACR,aAMA,IAAIE,EAAW,CAEbC,SAAU,SACVC,aAAc,SAGdC,QAAQ,EACRC,YAAa,SAGbC,OAAQ,EACRC,QAAQ,EAGRC,QAAQ,GA6BNC,EAAY,SAAUC,EAAMC,EAAMC,GAEpC,GAAKA,EAAOC,SAASL,OAArB,CAGA,IAAIM,EAAQ,IAAIC,YAAYL,EAAM,CAChCM,SAAS,EACTC,YAAY,EACZL,OAAQA,IAIVD,EAAKO,cAAcJ,EAVgB,CAWrC,EAOIK,EAAe,SAAUR,GAC3B,IAAIS,EAAW,EACf,GAAIT,EAAKU,aACP,KAAOV,GACLS,GAAYT,EAAKW,UACjBX,EAAOA,EAAKU,aAGhB,OAAOD,GAAY,EAAIA,EAAW,CACpC,EAMIG,EAAe,SAAUC,GACvBA,GACFA,EAASC,MAAK,SAAUC,EAAOC,GAG7B,OAFcR,EAAaO,EAAME,SACnBT,EAAaQ,EAAMC,UACF,EACxB,CACT,GAEJ,EAwCIC,EAAW,SAAUlB,EAAME,EAAUiB,GACvC,IAAIC,EAASpB,EAAKqB,wBACd1B,EAnCU,SAAUO,GAExB,MAA+B,mBAApBA,EAASP,OACX2B,WAAWpB,EAASP,UAItB2B,WAAWpB,EAASP,OAC7B,CA2Be4B,CAAUrB,GACvB,OAAIiB,EAEAK,SAASJ,EAAOD,OAAQ,KACvB/B,EAAOqC,aAAeC,SAASC,gBAAgBC,cAG7CJ,SAASJ,EAAOS,IAAK,KAAOlC,CACrC,EAMImC,EAAa,WACf,OACEC,KAAKC,KAAK5C,EAAOqC,YAAcrC,EAAO6C,cAnCjCF,KAAKG,IACVR,SAASS,KAAKC,aACdV,SAASC,gBAAgBS,aACzBV,SAASS,KAAKE,aACdX,SAASC,gBAAgBU,aACzBX,SAASS,KAAKP,aACdF,SAASC,gBAAgBC,aAkC7B,EAmBIU,EAAY,SAAUzB,EAAUX,GAClC,IAAIqC,EAAO1B,EAASA,EAAS2B,OAAS,GACtC,GAbgB,SAAUC,EAAMvC,GAChC,SAAI4B,MAAgBZ,EAASuB,EAAKxB,QAASf,GAAU,GAEvD,CAUMwC,CAAYH,EAAMrC,GAAW,OAAOqC,EACxC,IAAK,IAAII,EAAI9B,EAAS2B,OAAS,EAAGG,GAAK,EAAGA,IACxC,GAAIzB,EAASL,EAAS8B,GAAG1B,QAASf,GAAW,OAAOW,EAAS8B,EAEjE,EAOIC,EAAmB,SAAUC,EAAK3C,GAEpC,GAAKA,EAAST,QAAWoD,EAAIC,WAA7B,CAGA,IAAIC,EAAKF,EAAIC,WAAWE,QAAQ,MAC3BD,IAGLA,EAAGE,UAAUC,OAAOhD,EAASR,aAG7BkD,EAAiBG,EAAI7C,GAV0B,CAWjD,EAOIiD,EAAa,SAAUC,EAAOlD,GAEhC,GAAKkD,EAAL,CAGA,IAAIL,EAAKK,EAAMP,IAAIG,QAAQ,MACtBD,IAGLA,EAAGE,UAAUC,OAAOhD,EAASX,UAC7B6D,EAAMnC,QAAQgC,UAAUC,OAAOhD,EAASV,cAGxCoD,EAAiBG,EAAI7C,GAGrBJ,EAAU,oBAAqBiD,EAAI,CACjCM,KAAMD,EAAMP,IACZ5B,QAASmC,EAAMnC,QACff,SAAUA,IAjBM,CAmBpB,EAOIoD,EAAiB,SAAUT,EAAK3C,GAElC,GAAKA,EAAST,OAAd,CAGA,IAAIsD,EAAKF,EAAIC,WAAWE,QAAQ,MAC3BD,IAGLA,EAAGE,UAAUM,IAAIrD,EAASR,aAG1B4D,EAAeP,EAAI7C,GAVS,CAW9B,EA6LA,OA1JkB,SAAUsD,EAAUC,GAKpC,IACIC,EAAU7C,EAAU8C,EAASC,EAAS1D,EADtC2D,EAAa,CAUjBA,MAAmB,WAEjBH,EAAWhC,SAASoC,iBAAiBN,GAGrC3C,EAAW,GAGXkD,MAAMC,UAAUC,QAAQC,KAAKR,GAAU,SAAUjB,GAE/C,IAAIxB,EAAUS,SAASyC,eACrBC,mBAAmB3B,EAAK4B,KAAKC,OAAO,KAEjCrD,GAGLJ,EAAS0D,KAAK,CACZ1B,IAAKJ,EACLxB,QAASA,GAEb,IAGAL,EAAaC,EACf,EAKAgD,OAAoB,WAElB,IAAIW,EAASlC,EAAUzB,EAAUX,GAG5BsE,EASDb,GAAWa,EAAOvD,UAAY0C,EAAQ1C,UAG1CkC,EAAWQ,EAASzD,GAzFT,SAAUkD,EAAOlD,GAE9B,GAAKkD,EAAL,CAGA,IAAIL,EAAKK,EAAMP,IAAIG,QAAQ,MACtBD,IAGLA,EAAGE,UAAUM,IAAIrD,EAASX,UAC1B6D,EAAMnC,QAAQgC,UAAUM,IAAIrD,EAASV,cAGrC8D,EAAeP,EAAI7C,GAGnBJ,EAAU,kBAAmBiD,EAAI,CAC/BM,KAAMD,EAAMP,IACZ5B,QAASmC,EAAMnC,QACff,SAAUA,IAjBM,CAmBpB,CAqEIuE,CAASD,EAAQtE,GAGjByD,EAAUa,GAfJb,IACFR,EAAWQ,EAASzD,GACpByD,EAAU,KAchB,GAMIe,EAAgB,SAAUvE,GAExByD,GACFxE,EAAOuF,qBAAqBf,GAI9BA,EAAUxE,EAAOwF,sBAAsBf,EAAWgB,OACpD,EAMIC,EAAgB,SAAU3E,GAExByD,GACFxE,EAAOuF,qBAAqBf,GAI9BA,EAAUxE,EAAOwF,uBAAsB,WACrChE,EAAaC,GACbgD,EAAWgB,QACb,GACF,EAkDA,OA7CAhB,EAAWkB,QAAU,WAEfpB,GACFR,EAAWQ,EAASzD,GAItBd,EAAO4F,oBAAoB,SAAUN,GAAe,GAChDxE,EAASN,QACXR,EAAO4F,oBAAoB,SAAUF,GAAe,GAItDjE,EAAW,KACX6C,EAAW,KACXC,EAAU,KACVC,EAAU,KACV1D,EAAW,IACb,EAOEA,EA3XS,WACX,IAAI+E,EAAS,CAAC,EAOd,OANAlB,MAAMC,UAAUC,QAAQC,KAAKgB,WAAW,SAAUC,GAChD,IAAK,IAAIC,KAAOD,EAAK,CACnB,IAAKA,EAAIE,eAAeD,GAAM,OAC9BH,EAAOG,GAAOD,EAAIC,EACpB,CACF,IACOH,CACT,CAkXeK,CAAOhG,EAAUmE,GAAW,CAAC,GAGxCI,EAAW0B,QAGX1B,EAAWgB,SAGXzF,EAAOoG,iBAAiB,SAAUd,GAAe,GAC7CxE,EAASN,QACXR,EAAOoG,iBAAiB,SAAUV,GAAe,GAS9CjB,CACT,CAOF,CArcW4B,CAAQvG,EAChB,UAFM,SAEN,uBCXDwG,EAA2B,CAAC,EAGhC,SAASC,EAAoBC,GAE5B,IAAIC,EAAeH,EAAyBE,GAC5C,QAAqBE,IAAjBD,EACH,OAAOA,EAAaE,QAGrB,IAAIC,EAASN,EAAyBE,GAAY,CAGjDG,QAAS,CAAC,GAOX,OAHAE,EAAoBL,GAAU1B,KAAK8B,EAAOD,QAASC,EAAQA,EAAOD,QAASJ,GAGpEK,EAAOD,OACf,CCrBAJ,EAAoBO,EAAKF,IACxB,IAAIG,EAASH,GAAUA,EAAOI,WAC7B,IAAOJ,EAAiB,QACxB,IAAM,EAEP,OADAL,EAAoBU,EAAEF,EAAQ,CAAEG,EAAGH,IAC5BA,CAAM,ECLdR,EAAoBU,EAAI,CAACN,EAASQ,KACjC,IAAI,IAAInB,KAAOmB,EACXZ,EAAoBa,EAAED,EAAYnB,KAASO,EAAoBa,EAAET,EAASX,IAC5EqB,OAAOC,eAAeX,EAASX,EAAK,CAAEuB,YAAY,EAAMC,IAAKL,EAAWnB,IAE1E,ECNDO,EAAoBxG,EAAI,WACvB,GAA0B,iBAAf0H,WAAyB,OAAOA,WAC3C,IACC,OAAOxH,MAAQ,IAAIyH,SAAS,cAAb,EAChB,CAAE,MAAOC,GACR,GAAsB,iBAAX3H,OAAqB,OAAOA,MACxC,CACA,CAPuB,GCAxBuG,EAAoBa,EAAI,CAACrB,EAAK6B,IAAUP,OAAOzC,UAAUqB,eAAenB,KAAKiB,EAAK6B,4CCK9EC,EAAY,KACZC,EAAS,KACTC,EAAgBzF,SAASC,gBAAgByF,UAC7C,MAAMC,EAAmB,GA8EzB,SAASC,IACP,MAAMC,EAAeC,aAAaC,QAAQ,UAAY,OAZxD,IAAkBC,EACH,WADGA,EAaItI,OAAOuI,WAAW,gCAAgCC,QAI/C,SAAjBL,EACO,QACgB,SAAhBA,EACA,OAEA,OAIU,SAAjBA,EACO,OACgB,QAAhBA,EACA,QAEA,SA9BoB,SAATG,GAA4B,SAATA,IACzCG,QAAQC,MAAM,2BAA2BJ,yBACzCA,EAAO,QAGThG,SAASS,KAAK4F,QAAQC,MAAQN,EAC9BF,aAAaS,QAAQ,QAASP,GAC9BG,QAAQK,IAAI,cAAcR,UA0B5B,CAkDA,SAASnC,KART,WAEE,MAAM4C,EAAUzG,SAAS0G,uBAAuB,gBAChDrE,MAAMsE,KAAKF,GAASlE,SAASqE,IAC3BA,EAAI9C,iBAAiB,QAAS8B,EAAe,GAEjD,CAGEiB,GA9CF,WAEE,IAAIC,EAA6B,EAC7BC,GAAU,EAEdrJ,OAAOoG,iBAAiB,UAAU,SAAUuB,GAC1CyB,EAA6BpJ,OAAOsJ,QAE/BD,IACHrJ,OAAOwF,uBAAsB,WAzDnC,IAAuB+D,GAxDvB,SAAgCA,GAC9B,MAAMC,EAAY7G,KAAK8G,MAAM3B,EAAO7F,wBAAwBQ,KAE5DgG,QAAQK,IAAI,cAAcU,KACT,GAAbA,GAAkBD,GAAaC,EACjC1B,EAAOjE,UAAUM,IAAI,YAErB2D,EAAOjE,UAAUC,OAAO,WAE5B,EAgDE4F,CADqBH,EA0DDH,GAvGtB,SAAmCG,GAC7BA,EAAYtB,EACd3F,SAASC,gBAAgBsB,UAAUC,OAAO,oBAEtCyF,EAAYxB,EACdzF,SAASC,gBAAgBsB,UAAUM,IAAI,oBAC9BoF,EAAYxB,GACrBzF,SAASC,gBAAgBsB,UAAUC,OAAO,oBAG9CiE,EAAgBwB,CAClB,CAoCEI,CAA0BJ,GAlC5B,SAA6BA,GACT,OAAd1B,IAKa,GAAb0B,EACF1B,EAAU+B,SAAS,EAAG,GAGtBjH,KAAKC,KAAK2G,IACV5G,KAAK8G,MAAMnH,SAASC,gBAAgBS,aAAehD,OAAOqC,aAE1DwF,EAAU+B,SAAS,EAAG/B,EAAU7E,cAGhBV,SAASuH,cAAc,mBAc3C,CAKEC,CAAoBP,GAwDdF,GAAU,CACZ,IAEAA,GAAU,EAEd,IACArJ,OAAO+J,QACT,CA6BEC,GA1BkB,OAAdnC,GAKJ,IAAI,IAAJ,CAAY,cAAe,CACzBrH,QAAQ,EACRyJ,WAAW,EACX9J,SAAU,iBACVI,OAAQ,KACN,IAAI2J,EAAMhI,WAAWiI,iBAAiB7H,SAASC,iBAAiB6H,UAChE,OAAOtC,EAAO7F,wBAAwBoI,OAAS,IAAMH,EAAM,CAAC,GAiBlE,CAcA5H,SAAS8D,iBAAiB,oBAT1B,WACE9D,SAASS,KAAKW,WAAWG,UAAUC,OAAO,SAE1CgE,EAASxF,SAASuH,cAAc,UAChChC,EAAYvF,SAASuH,cAAc,eAEnC1D,GACF","sources":["webpack:///./src/furo/assets/scripts/gumshoe-patched.js","webpack:///webpack/bootstrap","webpack:///webpack/runtime/compat get default export","webpack:///webpack/runtime/define property getters","webpack:///webpack/runtime/global","webpack:///webpack/runtime/hasOwnProperty shorthand","webpack:///./src/furo/assets/scripts/furo.js"],"sourcesContent":["/*!\n * gumshoejs v5.1.2 (patched by @pradyunsg)\n * A simple, framework-agnostic scrollspy script.\n * (c) 2019 Chris Ferdinandi\n * MIT License\n * http://github.com/cferdinandi/gumshoe\n */\n\n(function (root, factory) {\n if (typeof define === \"function\" && define.amd) {\n define([], function () {\n return factory(root);\n });\n } else if (typeof exports === \"object\") {\n module.exports = factory(root);\n } else {\n root.Gumshoe = factory(root);\n }\n})(\n typeof global !== \"undefined\"\n ? global\n : typeof window !== \"undefined\"\n ? window\n : this,\n function (window) {\n \"use strict\";\n\n //\n // Defaults\n //\n\n var defaults = {\n // Active classes\n navClass: \"active\",\n contentClass: \"active\",\n\n // Nested navigation\n nested: false,\n nestedClass: \"active\",\n\n // Offset & reflow\n offset: 0,\n reflow: false,\n\n // Event support\n events: true,\n };\n\n //\n // Methods\n //\n\n /**\n * Merge two or more objects together.\n * @param {Object} objects The objects to merge together\n * @returns {Object} Merged values of defaults and options\n */\n var extend = function () {\n var merged = {};\n Array.prototype.forEach.call(arguments, function (obj) {\n for (var key in obj) {\n if (!obj.hasOwnProperty(key)) return;\n merged[key] = obj[key];\n }\n });\n return merged;\n };\n\n /**\n * Emit a custom event\n * @param {String} type The event type\n * @param {Node} elem The element to attach the event to\n * @param {Object} detail Any details to pass along with the event\n */\n var emitEvent = function (type, elem, detail) {\n // Make sure events are enabled\n if (!detail.settings.events) return;\n\n // Create a new event\n var event = new CustomEvent(type, {\n bubbles: true,\n cancelable: true,\n detail: detail,\n });\n\n // Dispatch the event\n elem.dispatchEvent(event);\n };\n\n /**\n * Get an element's distance from the top of the Document.\n * @param {Node} elem The element\n * @return {Number} Distance from the top in pixels\n */\n var getOffsetTop = function (elem) {\n var location = 0;\n if (elem.offsetParent) {\n while (elem) {\n location += elem.offsetTop;\n elem = elem.offsetParent;\n }\n }\n return location >= 0 ? location : 0;\n };\n\n /**\n * Sort content from first to last in the DOM\n * @param {Array} contents The content areas\n */\n var sortContents = function (contents) {\n if (contents) {\n contents.sort(function (item1, item2) {\n var offset1 = getOffsetTop(item1.content);\n var offset2 = getOffsetTop(item2.content);\n if (offset1 < offset2) return -1;\n return 1;\n });\n }\n };\n\n /**\n * Get the offset to use for calculating position\n * @param {Object} settings The settings for this instantiation\n * @return {Float} The number of pixels to offset the calculations\n */\n var getOffset = function (settings) {\n // if the offset is a function run it\n if (typeof settings.offset === \"function\") {\n return parseFloat(settings.offset());\n }\n\n // Otherwise, return it as-is\n return parseFloat(settings.offset);\n };\n\n /**\n * Get the document element's height\n * @private\n * @returns {Number}\n */\n var getDocumentHeight = function () {\n return Math.max(\n document.body.scrollHeight,\n document.documentElement.scrollHeight,\n document.body.offsetHeight,\n document.documentElement.offsetHeight,\n document.body.clientHeight,\n document.documentElement.clientHeight,\n );\n };\n\n /**\n * Determine if an element is in view\n * @param {Node} elem The element\n * @param {Object} settings The settings for this instantiation\n * @param {Boolean} bottom If true, check if element is above bottom of viewport instead\n * @return {Boolean} Returns true if element is in the viewport\n */\n var isInView = function (elem, settings, bottom) {\n var bounds = elem.getBoundingClientRect();\n var offset = getOffset(settings);\n if (bottom) {\n return (\n parseInt(bounds.bottom, 10) <\n (window.innerHeight || document.documentElement.clientHeight)\n );\n }\n return parseInt(bounds.top, 10) <= offset;\n };\n\n /**\n * Check if at the bottom of the viewport\n * @return {Boolean} If true, page is at the bottom of the viewport\n */\n var isAtBottom = function () {\n if (\n Math.ceil(window.innerHeight + window.pageYOffset) >=\n getDocumentHeight()\n )\n return true;\n return false;\n };\n\n /**\n * Check if the last item should be used (even if not at the top of the page)\n * @param {Object} item The last item\n * @param {Object} settings The settings for this instantiation\n * @return {Boolean} If true, use the last item\n */\n var useLastItem = function (item, settings) {\n if (isAtBottom() && isInView(item.content, settings, true)) return true;\n return false;\n };\n\n /**\n * Get the active content\n * @param {Array} contents The content areas\n * @param {Object} settings The settings for this instantiation\n * @return {Object} The content area and matching navigation link\n */\n var getActive = function (contents, settings) {\n var last = contents[contents.length - 1];\n if (useLastItem(last, settings)) return last;\n for (var i = contents.length - 1; i >= 0; i--) {\n if (isInView(contents[i].content, settings)) return contents[i];\n }\n };\n\n /**\n * Deactivate parent navs in a nested navigation\n * @param {Node} nav The starting navigation element\n * @param {Object} settings The settings for this instantiation\n */\n var deactivateNested = function (nav, settings) {\n // If nesting isn't activated, bail\n if (!settings.nested || !nav.parentNode) return;\n\n // Get the parent navigation\n var li = nav.parentNode.closest(\"li\");\n if (!li) return;\n\n // Remove the active class\n li.classList.remove(settings.nestedClass);\n\n // Apply recursively to any parent navigation elements\n deactivateNested(li, settings);\n };\n\n /**\n * Deactivate a nav and content area\n * @param {Object} items The nav item and content to deactivate\n * @param {Object} settings The settings for this instantiation\n */\n var deactivate = function (items, settings) {\n // Make sure there are items to deactivate\n if (!items) return;\n\n // Get the parent list item\n var li = items.nav.closest(\"li\");\n if (!li) return;\n\n // Remove the active class from the nav and content\n li.classList.remove(settings.navClass);\n items.content.classList.remove(settings.contentClass);\n\n // Deactivate any parent navs in a nested navigation\n deactivateNested(li, settings);\n\n // Emit a custom event\n emitEvent(\"gumshoeDeactivate\", li, {\n link: items.nav,\n content: items.content,\n settings: settings,\n });\n };\n\n /**\n * Activate parent navs in a nested navigation\n * @param {Node} nav The starting navigation element\n * @param {Object} settings The settings for this instantiation\n */\n var activateNested = function (nav, settings) {\n // If nesting isn't activated, bail\n if (!settings.nested) return;\n\n // Get the parent navigation\n var li = nav.parentNode.closest(\"li\");\n if (!li) return;\n\n // Add the active class\n li.classList.add(settings.nestedClass);\n\n // Apply recursively to any parent navigation elements\n activateNested(li, settings);\n };\n\n /**\n * Activate a nav and content area\n * @param {Object} items The nav item and content to activate\n * @param {Object} settings The settings for this instantiation\n */\n var activate = function (items, settings) {\n // Make sure there are items to activate\n if (!items) return;\n\n // Get the parent list item\n var li = items.nav.closest(\"li\");\n if (!li) return;\n\n // Add the active class to the nav and content\n li.classList.add(settings.navClass);\n items.content.classList.add(settings.contentClass);\n\n // Activate any parent navs in a nested navigation\n activateNested(li, settings);\n\n // Emit a custom event\n emitEvent(\"gumshoeActivate\", li, {\n link: items.nav,\n content: items.content,\n settings: settings,\n });\n };\n\n /**\n * Create the Constructor object\n * @param {String} selector The selector to use for navigation items\n * @param {Object} options User options and settings\n */\n var Constructor = function (selector, options) {\n //\n // Variables\n //\n\n var publicAPIs = {};\n var navItems, contents, current, timeout, settings;\n\n //\n // Methods\n //\n\n /**\n * Set variables from DOM elements\n */\n publicAPIs.setup = function () {\n // Get all nav items\n navItems = document.querySelectorAll(selector);\n\n // Create contents array\n contents = [];\n\n // Loop through each item, get it's matching content, and push to the array\n Array.prototype.forEach.call(navItems, function (item) {\n // Get the content for the nav item\n var content = document.getElementById(\n decodeURIComponent(item.hash.substr(1)),\n );\n if (!content) return;\n\n // Push to the contents array\n contents.push({\n nav: item,\n content: content,\n });\n });\n\n // Sort contents by the order they appear in the DOM\n sortContents(contents);\n };\n\n /**\n * Detect which content is currently active\n */\n publicAPIs.detect = function () {\n // Get the active content\n var active = getActive(contents, settings);\n\n // if there's no active content, deactivate and bail\n if (!active) {\n if (current) {\n deactivate(current, settings);\n current = null;\n }\n return;\n }\n\n // If the active content is the one currently active, do nothing\n if (current && active.content === current.content) return;\n\n // Deactivate the current content and activate the new content\n deactivate(current, settings);\n activate(active, settings);\n\n // Update the currently active content\n current = active;\n };\n\n /**\n * Detect the active content on scroll\n * Debounced for performance\n */\n var scrollHandler = function (event) {\n // If there's a timer, cancel it\n if (timeout) {\n window.cancelAnimationFrame(timeout);\n }\n\n // Setup debounce callback\n timeout = window.requestAnimationFrame(publicAPIs.detect);\n };\n\n /**\n * Update content sorting on resize\n * Debounced for performance\n */\n var resizeHandler = function (event) {\n // If there's a timer, cancel it\n if (timeout) {\n window.cancelAnimationFrame(timeout);\n }\n\n // Setup debounce callback\n timeout = window.requestAnimationFrame(function () {\n sortContents(contents);\n publicAPIs.detect();\n });\n };\n\n /**\n * Destroy the current instantiation\n */\n publicAPIs.destroy = function () {\n // Undo DOM changes\n if (current) {\n deactivate(current, settings);\n }\n\n // Remove event listeners\n window.removeEventListener(\"scroll\", scrollHandler, false);\n if (settings.reflow) {\n window.removeEventListener(\"resize\", resizeHandler, false);\n }\n\n // Reset variables\n contents = null;\n navItems = null;\n current = null;\n timeout = null;\n settings = null;\n };\n\n /**\n * Initialize the current instantiation\n */\n var init = function () {\n // Merge user options into defaults\n settings = extend(defaults, options || {});\n\n // Setup variables based on the current DOM\n publicAPIs.setup();\n\n // Find the currently active content\n publicAPIs.detect();\n\n // Setup event listeners\n window.addEventListener(\"scroll\", scrollHandler, false);\n if (settings.reflow) {\n window.addEventListener(\"resize\", resizeHandler, false);\n }\n };\n\n //\n // Initialize and return the public APIs\n //\n\n init();\n return publicAPIs;\n };\n\n //\n // Return the Constructor\n //\n\n return Constructor;\n },\n);\n","// The module cache\nvar __webpack_module_cache__ = {};\n\n// The require function\nfunction __webpack_require__(moduleId) {\n\t// Check if module is in cache\n\tvar cachedModule = __webpack_module_cache__[moduleId];\n\tif (cachedModule !== undefined) {\n\t\treturn cachedModule.exports;\n\t}\n\t// Create a new module (and put it into the cache)\n\tvar module = __webpack_module_cache__[moduleId] = {\n\t\t// no module.id needed\n\t\t// no module.loaded needed\n\t\texports: {}\n\t};\n\n\t// Execute the module function\n\t__webpack_modules__[moduleId].call(module.exports, module, module.exports, __webpack_require__);\n\n\t// Return the exports of the module\n\treturn module.exports;\n}\n\n","// getDefaultExport function for compatibility with non-harmony modules\n__webpack_require__.n = (module) => {\n\tvar getter = module && module.__esModule ?\n\t\t() => (module['default']) :\n\t\t() => (module);\n\t__webpack_require__.d(getter, { a: getter });\n\treturn getter;\n};","// define getter functions for harmony exports\n__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n\t\t}\n\t}\n};","__webpack_require__.g = (function() {\n\tif (typeof globalThis === 'object') return globalThis;\n\ttry {\n\t\treturn this || new Function('return this')();\n\t} catch (e) {\n\t\tif (typeof window === 'object') return window;\n\t}\n})();","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","import Gumshoe from \"./gumshoe-patched.js\";\n\n////////////////////////////////////////////////////////////////////////////////\n// Scroll Handling\n////////////////////////////////////////////////////////////////////////////////\nvar tocScroll = null;\nvar header = null;\nvar lastScrollTop = document.documentElement.scrollTop;\nconst GO_TO_TOP_OFFSET = 64;\n\nfunction scrollHandlerForHeader(positionY) {\n const headerTop = Math.floor(header.getBoundingClientRect().top);\n\n console.log(`headerTop: ${headerTop}`);\n if (headerTop == 0 && positionY != headerTop) {\n header.classList.add(\"scrolled\");\n } else {\n header.classList.remove(\"scrolled\");\n }\n}\n\nfunction scrollHandlerForBackToTop(positionY) {\n if (positionY < GO_TO_TOP_OFFSET) {\n document.documentElement.classList.remove(\"show-back-to-top\");\n } else {\n if (positionY < lastScrollTop) {\n document.documentElement.classList.add(\"show-back-to-top\");\n } else if (positionY > lastScrollTop) {\n document.documentElement.classList.remove(\"show-back-to-top\");\n }\n }\n lastScrollTop = positionY;\n}\n\nfunction scrollHandlerForTOC(positionY) {\n if (tocScroll === null) {\n return;\n }\n\n // top of page.\n if (positionY == 0) {\n tocScroll.scrollTo(0, 0);\n } else if (\n // bottom of page.\n Math.ceil(positionY) >=\n Math.floor(document.documentElement.scrollHeight - window.innerHeight)\n ) {\n tocScroll.scrollTo(0, tocScroll.scrollHeight);\n } else {\n // somewhere in the middle.\n const current = document.querySelector(\".scroll-current\");\n if (current == null) {\n return;\n }\n\n // https://github.com/pypa/pip/issues/9159 This breaks scroll behaviours.\n // // scroll the currently \"active\" heading in toc, into view.\n // const rect = current.getBoundingClientRect();\n // if (0 > rect.top) {\n // current.scrollIntoView(true); // the argument is \"alignTop\"\n // } else if (rect.bottom > window.innerHeight) {\n // current.scrollIntoView(false);\n // }\n }\n}\n\nfunction scrollHandler(positionY) {\n scrollHandlerForHeader(positionY);\n scrollHandlerForBackToTop(positionY);\n scrollHandlerForTOC(positionY);\n}\n\n////////////////////////////////////////////////////////////////////////////////\n// Theme Toggle\n////////////////////////////////////////////////////////////////////////////////\nfunction setTheme(mode) {\n if (mode !== \"light\" && mode !== \"dark\" && mode !== \"auto\") {\n console.error(`Got invalid theme mode: ${mode}. Resetting to auto.`);\n mode = \"auto\";\n }\n\n document.body.dataset.theme = mode;\n localStorage.setItem(\"theme\", mode);\n console.log(`Changed to ${mode} mode.`);\n}\n\nfunction cycleThemeOnce() {\n const currentTheme = localStorage.getItem(\"theme\") || \"auto\";\n const prefersDark = window.matchMedia(\"(prefers-color-scheme: dark)\").matches;\n\n if (prefersDark) {\n // Auto (dark) -> Light -> Dark\n if (currentTheme === \"auto\") {\n setTheme(\"light\");\n } else if (currentTheme == \"light\") {\n setTheme(\"dark\");\n } else {\n setTheme(\"auto\");\n }\n } else {\n // Auto (light) -> Dark -> Light\n if (currentTheme === \"auto\") {\n setTheme(\"dark\");\n } else if (currentTheme == \"dark\") {\n setTheme(\"light\");\n } else {\n setTheme(\"auto\");\n }\n }\n}\n\n////////////////////////////////////////////////////////////////////////////////\n// Setup\n////////////////////////////////////////////////////////////////////////////////\nfunction setupScrollHandler() {\n // Taken from https://developer.mozilla.org/en-US/docs/Web/API/Document/scroll_event\n let last_known_scroll_position = 0;\n let ticking = false;\n\n window.addEventListener(\"scroll\", function (e) {\n last_known_scroll_position = window.scrollY;\n\n if (!ticking) {\n window.requestAnimationFrame(function () {\n scrollHandler(last_known_scroll_position);\n ticking = false;\n });\n\n ticking = true;\n }\n });\n window.scroll();\n}\n\nfunction setupScrollSpy() {\n if (tocScroll === null) {\n return;\n }\n\n // Scrollspy -- highlight table on contents, based on scroll\n new Gumshoe(\".toc-tree a\", {\n reflow: true,\n recursive: true,\n navClass: \"scroll-current\",\n offset: () => {\n let rem = parseFloat(getComputedStyle(document.documentElement).fontSize);\n return header.getBoundingClientRect().height + 2.5 * rem + 1;\n },\n });\n}\n\nfunction setupTheme() {\n // Attach event handlers for toggling themes\n const buttons = document.getElementsByClassName(\"theme-toggle\");\n Array.from(buttons).forEach((btn) => {\n btn.addEventListener(\"click\", cycleThemeOnce);\n });\n}\n\nfunction setup() {\n setupTheme();\n setupScrollHandler();\n setupScrollSpy();\n}\n\n////////////////////////////////////////////////////////////////////////////////\n// Main entrypoint\n////////////////////////////////////////////////////////////////////////////////\nfunction main() {\n document.body.parentNode.classList.remove(\"no-js\");\n\n header = document.querySelector(\"header\");\n tocScroll = document.querySelector(\".toc-scroll\");\n\n setup();\n}\n\ndocument.addEventListener(\"DOMContentLoaded\", main);\n"],"names":["root","g","window","this","defaults","navClass","contentClass","nested","nestedClass","offset","reflow","events","emitEvent","type","elem","detail","settings","event","CustomEvent","bubbles","cancelable","dispatchEvent","getOffsetTop","location","offsetParent","offsetTop","sortContents","contents","sort","item1","item2","content","isInView","bottom","bounds","getBoundingClientRect","parseFloat","getOffset","parseInt","innerHeight","document","documentElement","clientHeight","top","isAtBottom","Math","ceil","pageYOffset","max","body","scrollHeight","offsetHeight","getActive","last","length","item","useLastItem","i","deactivateNested","nav","parentNode","li","closest","classList","remove","deactivate","items","link","activateNested","add","selector","options","navItems","current","timeout","publicAPIs","querySelectorAll","Array","prototype","forEach","call","getElementById","decodeURIComponent","hash","substr","push","active","activate","scrollHandler","cancelAnimationFrame","requestAnimationFrame","detect","resizeHandler","destroy","removeEventListener","merged","arguments","obj","key","hasOwnProperty","extend","setup","addEventListener","factory","__webpack_module_cache__","__webpack_require__","moduleId","cachedModule","undefined","exports","module","__webpack_modules__","n","getter","__esModule","d","a","definition","o","Object","defineProperty","enumerable","get","globalThis","Function","e","prop","tocScroll","header","lastScrollTop","scrollTop","GO_TO_TOP_OFFSET","cycleThemeOnce","currentTheme","localStorage","getItem","mode","matchMedia","matches","console","error","dataset","theme","setItem","log","buttons","getElementsByClassName","from","btn","setupTheme","last_known_scroll_position","ticking","scrollY","positionY","headerTop","floor","scrollHandlerForHeader","scrollHandlerForBackToTop","scrollTo","querySelector","scrollHandlerForTOC","scroll","setupScrollHandler","recursive","rem","getComputedStyle","fontSize","height"],"sourceRoot":""} \ No newline at end of file diff --git a/_static/searchtools.js b/_static/searchtools.js new file mode 100644 index 00000000..2c774d17 --- /dev/null +++ b/_static/searchtools.js @@ -0,0 +1,632 @@ +/* + * Sphinx JavaScript utilities for the full-text search. + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename, kind] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +// Global search result kind enum, used by themes to style search results. +class SearchResultKind { + static get index() { return "index"; } + static get object() { return "object"; } + static get text() { return "text"; } + static get title() { return "title"; } +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename, kind] = item; + + let listItem = document.createElement("li"); + // Add a class representing the item's type: + // can be used by a theme's CSS selector for styling + // See SearchResultKind for the class names. + listItem.classList.add(`kind-${kind}`); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = Documentation.ngettext( + "Search finished, found one page matching the search query.", + "Search finished, found ${resultCount} pages matching the search query.", + resultCount, + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename, kind]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.setAttribute("role", "list"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename, kind]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + SearchResultKind.title, + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + SearchResultKind.index, + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + SearchResultKind.object, + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + SearchResultKind.text, + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/_static/skeleton.css b/_static/skeleton.css new file mode 100644 index 00000000..467c878c --- /dev/null +++ b/_static/skeleton.css @@ -0,0 +1,296 @@ +/* Some sane resets. */ +html { + height: 100%; +} + +body { + margin: 0; + min-height: 100%; +} + +/* All the flexbox magic! */ +body, +.sb-announcement, +.sb-content, +.sb-main, +.sb-container, +.sb-container__inner, +.sb-article-container, +.sb-footer-content, +.sb-header, +.sb-header-secondary, +.sb-footer { + display: flex; +} + +/* These order things vertically */ +body, +.sb-main, +.sb-article-container { + flex-direction: column; +} + +/* Put elements in the center */ +.sb-header, +.sb-header-secondary, +.sb-container, +.sb-content, +.sb-footer, +.sb-footer-content { + justify-content: center; +} +/* Put elements at the ends */ +.sb-article-container { + justify-content: space-between; +} + +/* These elements grow. */ +.sb-main, +.sb-content, +.sb-container, +article { + flex-grow: 1; +} + +/* Because padding making this wider is not fun */ +article { + box-sizing: border-box; +} + +/* The announcements element should never be wider than the page. */ +.sb-announcement { + max-width: 100%; +} + +.sb-sidebar-primary, +.sb-sidebar-secondary { + flex-shrink: 0; + width: 17rem; +} + +.sb-announcement__inner { + justify-content: center; + + box-sizing: border-box; + height: 3rem; + + overflow-x: auto; + white-space: nowrap; +} + +/* Sidebars, with checkbox-based toggle */ +.sb-sidebar-primary, +.sb-sidebar-secondary { + position: fixed; + height: 100%; + top: 0; +} + +.sb-sidebar-primary { + left: -17rem; + transition: left 250ms ease-in-out; +} +.sb-sidebar-secondary { + right: -17rem; + transition: right 250ms ease-in-out; +} + +.sb-sidebar-toggle { + display: none; +} +.sb-sidebar-overlay { + position: fixed; + top: 0; + width: 0; + height: 0; + + transition: width 0ms ease 250ms, height 0ms ease 250ms, opacity 250ms ease; + + opacity: 0; + background-color: rgba(0, 0, 0, 0.54); +} + +#sb-sidebar-toggle--primary:checked + ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--primary"], +#sb-sidebar-toggle--secondary:checked + ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--secondary"] { + width: 100%; + height: 100%; + opacity: 1; + transition: width 0ms ease, height 0ms ease, opacity 250ms ease; +} + +#sb-sidebar-toggle--primary:checked ~ .sb-container .sb-sidebar-primary { + left: 0; +} +#sb-sidebar-toggle--secondary:checked ~ .sb-container .sb-sidebar-secondary { + right: 0; +} + +/* Full-width mode */ +.drop-secondary-sidebar-for-full-width-content + .hide-when-secondary-sidebar-shown { + display: none !important; +} +.drop-secondary-sidebar-for-full-width-content .sb-sidebar-secondary { + display: none !important; +} + +/* Mobile views */ +.sb-page-width { + width: 100%; +} + +.sb-article-container, +.sb-footer-content__inner, +.drop-secondary-sidebar-for-full-width-content .sb-article, +.drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 100vw; +} + +.sb-article, +.match-content-width { + padding: 0 1rem; + box-sizing: border-box; +} + +@media (min-width: 32rem) { + .sb-article, + .match-content-width { + padding: 0 2rem; + } +} + +/* Tablet views */ +@media (min-width: 42rem) { + .sb-article-container { + width: auto; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 42rem; + } + .sb-article, + .match-content-width { + width: 42rem; + } +} +@media (min-width: 46rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 46rem; + } + .sb-article, + .match-content-width { + width: 46rem; + } +} +@media (min-width: 50rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 50rem; + } + .sb-article, + .match-content-width { + width: 50rem; + } +} + +/* Tablet views */ +@media (min-width: 59rem) { + .sb-sidebar-secondary { + position: static; + } + .hide-when-secondary-sidebar-shown { + display: none !important; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 59rem; + } + .sb-article, + .match-content-width { + width: 42rem; + } +} +@media (min-width: 63rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 63rem; + } + .sb-article, + .match-content-width { + width: 46rem; + } +} +@media (min-width: 67rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 67rem; + } + .sb-article, + .match-content-width { + width: 50rem; + } +} + +/* Desktop views */ +@media (min-width: 76rem) { + .sb-sidebar-primary { + position: static; + } + .hide-when-primary-sidebar-shown { + display: none !important; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 59rem; + } + .sb-article, + .match-content-width { + width: 42rem; + } +} + +/* Full desktop views */ +@media (min-width: 80rem) { + .sb-article, + .match-content-width { + width: 46rem; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 63rem; + } +} + +@media (min-width: 84rem) { + .sb-article, + .match-content-width { + width: 50rem; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 67rem; + } +} + +@media (min-width: 88rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 67rem; + } + .sb-page-width { + width: 88rem; + } +} diff --git a/_static/sphinx_highlight.js b/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/_static/styles/furo-extensions.css b/_static/styles/furo-extensions.css new file mode 100644 index 00000000..82295876 --- /dev/null +++ b/_static/styles/furo-extensions.css @@ -0,0 +1,2 @@ +#furo-sidebar-ad-placement{padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)}#furo-sidebar-ad-placement .ethical-sidebar{background:var(--color-background-secondary);border:none;box-shadow:none}#furo-sidebar-ad-placement .ethical-sidebar:hover{background:var(--color-background-hover)}#furo-sidebar-ad-placement .ethical-sidebar a{color:var(--color-foreground-primary)}#furo-sidebar-ad-placement .ethical-callout a{color:var(--color-foreground-secondary)!important}#furo-readthedocs-versions{background:transparent;display:block;position:static;width:100%}#furo-readthedocs-versions .rst-versions{background:#1a1c1e}#furo-readthedocs-versions .rst-current-version{background:var(--color-sidebar-item-background);cursor:unset}#furo-readthedocs-versions .rst-current-version:hover{background:var(--color-sidebar-item-background)}#furo-readthedocs-versions .rst-current-version .fa-book{color:var(--color-foreground-primary)}#furo-readthedocs-versions>.rst-other-versions{padding:0}#furo-readthedocs-versions>.rst-other-versions small{opacity:1}#furo-readthedocs-versions .injected .rst-versions{position:unset}#furo-readthedocs-versions:focus-within,#furo-readthedocs-versions:hover{box-shadow:0 0 0 1px var(--color-sidebar-background-border)}#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:hover .rst-current-version{background:#1a1c1e;font-size:inherit;height:auto;line-height:inherit;padding:12px;text-align:right}#furo-readthedocs-versions:focus-within .rst-current-version .fa-book,#furo-readthedocs-versions:hover .rst-current-version .fa-book{color:#fff;float:left}#furo-readthedocs-versions:focus-within .fa-caret-down,#furo-readthedocs-versions:hover .fa-caret-down{display:none}#furo-readthedocs-versions:focus-within .injected,#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:focus-within .rst-other-versions,#furo-readthedocs-versions:hover .injected,#furo-readthedocs-versions:hover .rst-current-version,#furo-readthedocs-versions:hover .rst-other-versions{display:block}#furo-readthedocs-versions:focus-within>.rst-current-version,#furo-readthedocs-versions:hover>.rst-current-version{display:none}.highlight:hover button.copybtn{color:var(--color-code-foreground)}.highlight button.copybtn{align-items:center;background-color:var(--color-code-background);border:none;color:var(--color-background-item);cursor:pointer;height:1.25em;right:.5rem;top:.625rem;transition:color .3s,opacity .3s;width:1.25em}.highlight button.copybtn:hover{background-color:var(--color-code-background);color:var(--color-brand-content)}.highlight button.copybtn:after{background-color:transparent;color:var(--color-code-foreground);display:none}.highlight button.copybtn.success{color:#22863a;transition:color 0ms}.highlight button.copybtn.success:after{display:block}.highlight button.copybtn svg{padding:0}body{--sd-color-primary:var(--color-brand-primary);--sd-color-primary-highlight:var(--color-brand-content);--sd-color-primary-text:var(--color-background-primary);--sd-color-shadow:rgba(0,0,0,.05);--sd-color-card-border:var(--color-card-border);--sd-color-card-border-hover:var(--color-brand-content);--sd-color-card-background:var(--color-card-background);--sd-color-card-text:var(--color-foreground-primary);--sd-color-card-header:var(--color-card-marginals-background);--sd-color-card-footer:var(--color-card-marginals-background);--sd-color-tabs-label-active:var(--color-brand-content);--sd-color-tabs-label-hover:var(--color-foreground-muted);--sd-color-tabs-label-inactive:var(--color-foreground-muted);--sd-color-tabs-underline-active:var(--color-brand-content);--sd-color-tabs-underline-hover:var(--color-foreground-border);--sd-color-tabs-underline-inactive:var(--color-background-border);--sd-color-tabs-overline:var(--color-background-border);--sd-color-tabs-underline:var(--color-background-border)}.sd-tab-content{box-shadow:0 -2px var(--sd-color-tabs-overline),0 1px var(--sd-color-tabs-underline)}.sd-card{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)}.sd-shadow-sm{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-md{box-shadow:0 .3rem .75rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-lg{box-shadow:0 .6rem 1.5rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-card-hover:hover{transform:none}.sd-cards-carousel{gap:.25rem;padding:.25rem}body{--tabs--label-text:var(--color-foreground-muted);--tabs--label-text--hover:var(--color-foreground-muted);--tabs--label-text--active:var(--color-brand-content);--tabs--label-text--active--hover:var(--color-brand-content);--tabs--label-background:transparent;--tabs--label-background--hover:transparent;--tabs--label-background--active:transparent;--tabs--label-background--active--hover:transparent;--tabs--padding-x:0.25em;--tabs--margin-x:1em;--tabs--border:var(--color-background-border);--tabs--label-border:transparent;--tabs--label-border--hover:var(--color-foreground-muted);--tabs--label-border--active:var(--color-brand-content);--tabs--label-border--active--hover:var(--color-brand-content)}[role=main] .container{max-width:none;padding-left:0;padding-right:0}.shadow.docutils{border:none;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1)!important}.sphinx-bs .card{background-color:var(--color-background-secondary);color:var(--color-foreground)} +/*# sourceMappingURL=furo-extensions.css.map*/ \ No newline at end of file diff --git a/_static/styles/furo-extensions.css.map b/_static/styles/furo-extensions.css.map new file mode 100644 index 00000000..c26eac7f --- /dev/null +++ b/_static/styles/furo-extensions.css.map @@ -0,0 +1 @@ +{"version":3,"file":"styles/furo-extensions.css","mappings":"AAGA,2BACE,oFACA,4CAKE,6CAHA,YACA,eAEA,CACA,kDACE,yCAEF,8CACE,sCAEJ,8CACE,kDAEJ,2BAGE,uBACA,cAHA,gBACA,UAEA,CAGA,yCACE,mBAEF,gDAEE,gDADA,YACA,CACA,sDACE,gDACF,yDACE,sCAEJ,+CACE,UACA,qDACE,UAGF,mDACE,eAEJ,yEAEE,4DAEA,mHASE,mBAPA,kBAEA,YADA,oBAGA,aADA,gBAIA,CAEA,qIAEE,WADA,UACA,CAEJ,uGACE,aAEF,iUAGE,cAEF,mHACE,aC1EJ,gCACE,mCAEF,0BAEE,mBAUA,8CACA,YAFA,mCAKA,eAZA,cAIA,YADA,YAYA,iCAdA,YAcA,CAEA,gCAEE,8CADA,gCACA,CAEF,gCAGE,6BADA,mCADA,YAEA,CAEF,kCAEE,cADA,oBACA,CACA,wCACE,cAEJ,8BACE,UCzCN,KAEE,6CAA8C,CAC9C,uDAAwD,CACxD,uDAAwD,CAGxD,iCAAsC,CAGtC,+CAAgD,CAChD,uDAAwD,CACxD,uDAAwD,CACxD,oDAAqD,CACrD,6DAA8D,CAC9D,6DAA8D,CAG9D,uDAAwD,CACxD,yDAA0D,CAC1D,4DAA6D,CAC7D,2DAA4D,CAC5D,8DAA+D,CAC/D,iEAAkE,CAClE,uDAAwD,CACxD,wDAAyD,CAG3D,gBACE,qFAGF,SACE,6EAEF,cACE,uFAEF,cACE,uFAEF,cACE,uFAGF,qBACE,eAEF,mBACE,WACA,eChDF,KACE,gDAAiD,CACjD,uDAAwD,CACxD,qDAAsD,CACtD,4DAA6D,CAC7D,oCAAqC,CACrC,2CAA4C,CAC5C,4CAA6C,CAC7C,mDAAoD,CACpD,wBAAyB,CACzB,oBAAqB,CACrB,6CAA8C,CAC9C,gCAAiC,CACjC,yDAA0D,CAC1D,uDAAwD,CACxD,8DAA+D,CCbjE,uBACE,eACA,eACA,gBAGF,iBACE,YACA,+EAGF,iBACE,mDACA","sources":["webpack:///./src/furo/assets/styles/extensions/_readthedocs.sass","webpack:///./src/furo/assets/styles/extensions/_copybutton.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-design.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-inline-tabs.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-panels.sass"],"sourcesContent":["// This file contains the styles used for tweaking how ReadTheDoc's embedded\n// contents would show up inside the theme.\n\n#furo-sidebar-ad-placement\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n .ethical-sidebar\n // Remove the border and box-shadow.\n border: none\n box-shadow: none\n // Manage the background colors.\n background: var(--color-background-secondary)\n &:hover\n background: var(--color-background-hover)\n // Ensure the text is legible.\n a\n color: var(--color-foreground-primary)\n\n .ethical-callout a\n color: var(--color-foreground-secondary) !important\n\n#furo-readthedocs-versions\n position: static\n width: 100%\n background: transparent\n display: block\n\n // Make the background color fit with the theme's aesthetic.\n .rst-versions\n background: rgb(26, 28, 30)\n\n .rst-current-version\n cursor: unset\n background: var(--color-sidebar-item-background)\n &:hover\n background: var(--color-sidebar-item-background)\n .fa-book\n color: var(--color-foreground-primary)\n\n > .rst-other-versions\n padding: 0\n small\n opacity: 1\n\n .injected\n .rst-versions\n position: unset\n\n &:hover,\n &:focus-within\n box-shadow: 0 0 0 1px var(--color-sidebar-background-border)\n\n .rst-current-version\n // Undo the tweaks done in RTD's CSS\n font-size: inherit\n line-height: inherit\n height: auto\n text-align: right\n padding: 12px\n\n // Match the rest of the body\n background: #1a1c1e\n\n .fa-book\n float: left\n color: white\n\n .fa-caret-down\n display: none\n\n .rst-current-version,\n .rst-other-versions,\n .injected\n display: block\n\n > .rst-current-version\n display: none\n",".highlight\n &:hover button.copybtn\n color: var(--color-code-foreground)\n\n button.copybtn\n // Align things correctly\n align-items: center\n\n height: 1.25em\n width: 1.25em\n\n top: 0.625rem // $code-spacing-vertical\n right: 0.5rem\n\n // Make it look better\n color: var(--color-background-item)\n background-color: var(--color-code-background)\n border: none\n\n // Change to cursor to make it obvious that you can click on it\n cursor: pointer\n\n // Transition smoothly, for aesthetics\n transition: color 300ms, opacity 300ms\n\n &:hover\n color: var(--color-brand-content)\n background-color: var(--color-code-background)\n\n &::after\n display: none\n color: var(--color-code-foreground)\n background-color: transparent\n\n &.success\n transition: color 0ms\n color: #22863a\n &::after\n display: block\n\n svg\n padding: 0\n","body\n // Colors\n --sd-color-primary: var(--color-brand-primary)\n --sd-color-primary-highlight: var(--color-brand-content)\n --sd-color-primary-text: var(--color-background-primary)\n\n // Shadows\n --sd-color-shadow: rgba(0, 0, 0, 0.05)\n\n // Cards\n --sd-color-card-border: var(--color-card-border)\n --sd-color-card-border-hover: var(--color-brand-content)\n --sd-color-card-background: var(--color-card-background)\n --sd-color-card-text: var(--color-foreground-primary)\n --sd-color-card-header: var(--color-card-marginals-background)\n --sd-color-card-footer: var(--color-card-marginals-background)\n\n // Tabs\n --sd-color-tabs-label-active: var(--color-brand-content)\n --sd-color-tabs-label-hover: var(--color-foreground-muted)\n --sd-color-tabs-label-inactive: var(--color-foreground-muted)\n --sd-color-tabs-underline-active: var(--color-brand-content)\n --sd-color-tabs-underline-hover: var(--color-foreground-border)\n --sd-color-tabs-underline-inactive: var(--color-background-border)\n --sd-color-tabs-overline: var(--color-background-border)\n --sd-color-tabs-underline: var(--color-background-border)\n\n// Tabs\n.sd-tab-content\n box-shadow: 0 -2px var(--sd-color-tabs-overline), 0 1px var(--sd-color-tabs-underline)\n\n// Shadows\n.sd-card // Have a shadow by default\n box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n.sd-shadow-sm\n box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-md\n box-shadow: 0 0.3rem 0.75rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-lg\n box-shadow: 0 0.6rem 1.5rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Cards\n.sd-card-hover:hover // Don't change scale on hover\n transform: none\n\n.sd-cards-carousel // Have a bit of gap in the carousel by default\n gap: 0.25rem\n padding: 0.25rem\n","// This file contains styles to tweak sphinx-inline-tabs to work well with Furo.\n\nbody\n --tabs--label-text: var(--color-foreground-muted)\n --tabs--label-text--hover: var(--color-foreground-muted)\n --tabs--label-text--active: var(--color-brand-content)\n --tabs--label-text--active--hover: var(--color-brand-content)\n --tabs--label-background: transparent\n --tabs--label-background--hover: transparent\n --tabs--label-background--active: transparent\n --tabs--label-background--active--hover: transparent\n --tabs--padding-x: 0.25em\n --tabs--margin-x: 1em\n --tabs--border: var(--color-background-border)\n --tabs--label-border: transparent\n --tabs--label-border--hover: var(--color-foreground-muted)\n --tabs--label-border--active: var(--color-brand-content)\n --tabs--label-border--active--hover: var(--color-brand-content)\n","// This file contains styles to tweak sphinx-panels to work well with Furo.\n\n// sphinx-panels includes Bootstrap 4, which uses .container which can conflict\n// with docutils' `.. container::` directive.\n[role=\"main\"] .container\n max-width: initial\n padding-left: initial\n padding-right: initial\n\n// Make the panels look nicer!\n.shadow.docutils\n border: none\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Make panel colors respond to dark mode\n.sphinx-bs .card\n background-color: var(--color-background-secondary)\n color: var(--color-foreground)\n"],"names":[],"sourceRoot":""} \ No newline at end of file diff --git a/_static/styles/furo.css b/_static/styles/furo.css new file mode 100644 index 00000000..05a56b17 --- /dev/null +++ b/_static/styles/furo.css @@ -0,0 +1,2 @@ +/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}main{display:block}h1{font-size:2em;margin:.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace,monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace,monospace;font-size:1em}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}[type=button],[type=reset],[type=submit],button{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{border-style:none;padding:0}[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring,button:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}[hidden],template{display:none}@media print{.content-icon-container,.headerlink,.mobile-header,.related-pages{display:none!important}.highlight{border:.1pt solid var(--color-foreground-border)}a,blockquote,dl,ol,p,pre,table,ul{page-break-inside:avoid}caption,figure,h1,h2,h3,h4,h5,h6,img{page-break-after:avoid;page-break-inside:avoid}dl,ol,ul{page-break-before:avoid}}.visually-hidden{height:1px!important;margin:-1px!important;overflow:hidden!important;padding:0!important;position:absolute!important;width:1px!important;clip:rect(0,0,0,0)!important;background:var(--color-background-primary);border:0!important;color:var(--color-foreground-primary);white-space:nowrap!important}:-moz-focusring{outline:auto}body{--font-stack:-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif,Apple Color Emoji,Segoe UI Emoji;--font-stack--monospace:"SFMono-Regular",Menlo,Consolas,Monaco,Liberation Mono,Lucida Console,monospace;--font-stack--headings:var(--font-stack);--font-size--normal:100%;--font-size--small:87.5%;--font-size--small--2:81.25%;--font-size--small--3:75%;--font-size--small--4:62.5%;--sidebar-caption-font-size:var(--font-size--small--2);--sidebar-item-font-size:var(--font-size--small);--sidebar-search-input-font-size:var(--font-size--small);--toc-font-size:var(--font-size--small--3);--toc-font-size--mobile:var(--font-size--normal);--toc-title-font-size:var(--font-size--small--4);--admonition-font-size:0.8125rem;--admonition-title-font-size:0.8125rem;--code-font-size:var(--font-size--small--2);--api-font-size:var(--font-size--small);--header-height:calc(var(--sidebar-item-line-height) + var(--sidebar-item-spacing-vertical)*4);--header-padding:0.5rem;--sidebar-tree-space-above:1.5rem;--sidebar-caption-space-above:1rem;--sidebar-item-line-height:1rem;--sidebar-item-spacing-vertical:0.5rem;--sidebar-item-spacing-horizontal:1rem;--sidebar-item-height:calc(var(--sidebar-item-line-height) + var(--sidebar-item-spacing-vertical)*2);--sidebar-expander-width:var(--sidebar-item-height);--sidebar-search-space-above:0.5rem;--sidebar-search-input-spacing-vertical:0.5rem;--sidebar-search-input-spacing-horizontal:0.5rem;--sidebar-search-input-height:1rem;--sidebar-search-icon-size:var(--sidebar-search-input-height);--toc-title-padding:0.25rem 0;--toc-spacing-vertical:1.5rem;--toc-spacing-horizontal:1.5rem;--toc-item-spacing-vertical:0.4rem;--toc-item-spacing-horizontal:1rem;--icon-search:url('data:image/svg+xml;charset=utf-8,');--icon-pencil:url('data:image/svg+xml;charset=utf-8,');--icon-abstract:url('data:image/svg+xml;charset=utf-8,');--icon-info:url('data:image/svg+xml;charset=utf-8,');--icon-flame:url('data:image/svg+xml;charset=utf-8,');--icon-question:url('data:image/svg+xml;charset=utf-8,');--icon-warning:url('data:image/svg+xml;charset=utf-8,');--icon-failure:url('data:image/svg+xml;charset=utf-8,');--icon-spark:url('data:image/svg+xml;charset=utf-8,');--color-admonition-title--caution:#ff9100;--color-admonition-title-background--caution:rgba(255,145,0,.2);--color-admonition-title--warning:#ff9100;--color-admonition-title-background--warning:rgba(255,145,0,.2);--color-admonition-title--danger:#ff5252;--color-admonition-title-background--danger:rgba(255,82,82,.2);--color-admonition-title--attention:#ff5252;--color-admonition-title-background--attention:rgba(255,82,82,.2);--color-admonition-title--error:#ff5252;--color-admonition-title-background--error:rgba(255,82,82,.2);--color-admonition-title--hint:#00c852;--color-admonition-title-background--hint:rgba(0,200,82,.2);--color-admonition-title--tip:#00c852;--color-admonition-title-background--tip:rgba(0,200,82,.2);--color-admonition-title--important:#00bfa5;--color-admonition-title-background--important:rgba(0,191,165,.2);--color-admonition-title--note:#00b0ff;--color-admonition-title-background--note:rgba(0,176,255,.2);--color-admonition-title--seealso:#448aff;--color-admonition-title-background--seealso:rgba(68,138,255,.2);--color-admonition-title--admonition-todo:grey;--color-admonition-title-background--admonition-todo:hsla(0,0%,50%,.2);--color-admonition-title:#651fff;--color-admonition-title-background:rgba(101,31,255,.2);--icon-admonition-default:var(--icon-abstract);--color-topic-title:#14b8a6;--color-topic-title-background:rgba(20,184,166,.2);--icon-topic-default:var(--icon-pencil);--color-problematic:#b30000;--color-foreground-primary:#000;--color-foreground-secondary:#5a5c63;--color-foreground-muted:#6b6f76;--color-foreground-border:#878787;--color-background-primary:#fff;--color-background-secondary:#f8f9fb;--color-background-hover:#efeff4;--color-background-hover--transparent:#efeff400;--color-background-border:#eeebee;--color-background-item:#ccc;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#0a4bff;--color-brand-content:#2757dd;--color-brand-visited:#872ee0;--color-api-background:var(--color-background-hover--transparent);--color-api-background-hover:var(--color-background-hover);--color-api-overall:var(--color-foreground-secondary);--color-api-name:var(--color-problematic);--color-api-pre-name:var(--color-problematic);--color-api-paren:var(--color-foreground-secondary);--color-api-keyword:var(--color-foreground-primary);--color-api-added:#21632c;--color-api-added-border:#38a84d;--color-api-changed:#046172;--color-api-changed-border:#06a1bc;--color-api-deprecated:#605706;--color-api-deprecated-border:#f0d90f;--color-api-removed:#b30000;--color-api-removed-border:#ff5c5c;--color-highlight-on-target:#ffc;--color-inline-code-background:var(--color-background-secondary);--color-highlighted-background:#def;--color-highlighted-text:var(--color-foreground-primary);--color-guilabel-background:#ddeeff80;--color-guilabel-border:#bedaf580;--color-guilabel-text:var(--color-foreground-primary);--color-admonition-background:transparent;--color-table-header-background:var(--color-background-secondary);--color-table-border:var(--color-background-border);--color-card-border:var(--color-background-secondary);--color-card-background:transparent;--color-card-marginals-background:var(--color-background-secondary);--color-header-background:var(--color-background-primary);--color-header-border:var(--color-background-border);--color-header-text:var(--color-foreground-primary);--color-sidebar-background:var(--color-background-secondary);--color-sidebar-background-border:var(--color-background-border);--color-sidebar-brand-text:var(--color-foreground-primary);--color-sidebar-caption-text:var(--color-foreground-muted);--color-sidebar-link-text:var(--color-foreground-secondary);--color-sidebar-link-text--top-level:var(--color-brand-primary);--color-sidebar-item-background:var(--color-sidebar-background);--color-sidebar-item-background--current:var( --color-sidebar-item-background );--color-sidebar-item-background--hover:linear-gradient(90deg,var(--color-background-hover--transparent) 0%,var(--color-background-hover) var(--sidebar-item-spacing-horizontal),var(--color-background-hover) 100%);--color-sidebar-item-expander-background:transparent;--color-sidebar-item-expander-background--hover:var( --color-background-hover );--color-sidebar-search-text:var(--color-foreground-primary);--color-sidebar-search-background:var(--color-background-secondary);--color-sidebar-search-background--focus:var(--color-background-primary);--color-sidebar-search-border:var(--color-background-border);--color-sidebar-search-icon:var(--color-foreground-muted);--color-toc-background:var(--color-background-primary);--color-toc-title-text:var(--color-foreground-muted);--color-toc-item-text:var(--color-foreground-secondary);--color-toc-item-text--hover:var(--color-foreground-primary);--color-toc-item-text--active:var(--color-brand-primary);--color-content-foreground:var(--color-foreground-primary);--color-content-background:transparent;--color-link:var(--color-brand-content);--color-link-underline:var(--color-background-border);--color-link--hover:var(--color-brand-content);--color-link-underline--hover:var(--color-foreground-border);--color-link--visited:var(--color-brand-visited);--color-link-underline--visited:var(--color-background-border);--color-link--visited--hover:var(--color-brand-visited);--color-link-underline--visited--hover:var(--color-foreground-border)}.only-light{display:block!important}html body .only-dark{display:none!important}@media not print{body[data-theme=dark]{--color-problematic:#ee5151;--color-foreground-primary:#cfd0d0;--color-foreground-secondary:#9ca0a5;--color-foreground-muted:#81868d;--color-foreground-border:#666;--color-background-primary:#131416;--color-background-secondary:#1a1c1e;--color-background-hover:#1e2124;--color-background-hover--transparent:#1e212400;--color-background-border:#303335;--color-background-item:#444;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#3d94ff;--color-brand-content:#5ca5ff;--color-brand-visited:#b27aeb;--color-highlighted-background:#083563;--color-guilabel-background:#08356380;--color-guilabel-border:#13395f80;--color-api-keyword:var(--color-foreground-secondary);--color-highlight-on-target:#330;--color-api-added:#3db854;--color-api-added-border:#267334;--color-api-changed:#09b0ce;--color-api-changed-border:#056d80;--color-api-deprecated:#b1a10b;--color-api-deprecated-border:#6e6407;--color-api-removed:#ff7575;--color-api-removed-border:#b03b3b;--color-admonition-background:#18181a;--color-card-border:var(--color-background-secondary);--color-card-background:#18181a;--color-card-marginals-background:var(--color-background-hover)}html body[data-theme=dark] .only-light{display:none!important}body[data-theme=dark] .only-dark{display:block!important}@media(prefers-color-scheme:dark){body:not([data-theme=light]){--color-problematic:#ee5151;--color-foreground-primary:#cfd0d0;--color-foreground-secondary:#9ca0a5;--color-foreground-muted:#81868d;--color-foreground-border:#666;--color-background-primary:#131416;--color-background-secondary:#1a1c1e;--color-background-hover:#1e2124;--color-background-hover--transparent:#1e212400;--color-background-border:#303335;--color-background-item:#444;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#3d94ff;--color-brand-content:#5ca5ff;--color-brand-visited:#b27aeb;--color-highlighted-background:#083563;--color-guilabel-background:#08356380;--color-guilabel-border:#13395f80;--color-api-keyword:var(--color-foreground-secondary);--color-highlight-on-target:#330;--color-api-added:#3db854;--color-api-added-border:#267334;--color-api-changed:#09b0ce;--color-api-changed-border:#056d80;--color-api-deprecated:#b1a10b;--color-api-deprecated-border:#6e6407;--color-api-removed:#ff7575;--color-api-removed-border:#b03b3b;--color-admonition-background:#18181a;--color-card-border:var(--color-background-secondary);--color-card-background:#18181a;--color-card-marginals-background:var(--color-background-hover)}html body:not([data-theme=light]) .only-light{display:none!important}body:not([data-theme=light]) .only-dark{display:block!important}}}body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto-light{display:block}@media(prefers-color-scheme:dark){body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto-dark{display:block}body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto-light{display:none}}body[data-theme=dark] .theme-toggle svg.theme-icon-when-dark,body[data-theme=light] .theme-toggle svg.theme-icon-when-light{display:block}body{font-family:var(--font-stack)}code,kbd,pre,samp{font-family:var(--font-stack--monospace)}body{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}article{line-height:1.5}h1,h2,h3,h4,h5,h6{border-radius:.5rem;font-family:var(--font-stack--headings);font-weight:700;line-height:1.25;margin:.5rem -.5rem;padding-left:.5rem;padding-right:.5rem}h1+p,h2+p,h3+p,h4+p,h5+p,h6+p{margin-top:0}h1{font-size:2.5em;margin-bottom:1rem}h1,h2{margin-top:1.75rem}h2{font-size:2em}h3{font-size:1.5em}h4{font-size:1.25em}h5{font-size:1.125em}h6{font-size:1em}small{font-size:80%;opacity:75%}p{margin-bottom:.75rem;margin-top:.5rem}hr.docutils{background-color:var(--color-background-border);border:0;height:1px;margin:2rem 0;padding:0}.centered{text-align:center}a{color:var(--color-link);text-decoration:underline;text-decoration-color:var(--color-link-underline)}a:visited{color:var(--color-link--visited);text-decoration-color:var(--color-link-underline--visited)}a:visited:hover{color:var(--color-link--visited--hover);text-decoration-color:var(--color-link-underline--visited--hover)}a:hover{color:var(--color-link--hover);text-decoration-color:var(--color-link-underline--hover)}a.muted-link{color:inherit}a.muted-link:hover{color:var(--color-link--hover);text-decoration-color:var(--color-link-underline--hover)}a.muted-link:hover:visited{color:var(--color-link--visited--hover);text-decoration-color:var(--color-link-underline--visited--hover)}html{overflow-x:hidden;overflow-y:scroll;scroll-behavior:smooth}.sidebar-scroll,.toc-scroll,article[role=main] *{scrollbar-color:var(--color-foreground-border) transparent;scrollbar-width:thin}.sidebar-scroll::-webkit-scrollbar,.toc-scroll::-webkit-scrollbar,article[role=main] ::-webkit-scrollbar{height:.25rem;width:.25rem}.sidebar-scroll::-webkit-scrollbar-thumb,.toc-scroll::-webkit-scrollbar-thumb,article[role=main] ::-webkit-scrollbar-thumb{background-color:var(--color-foreground-border);border-radius:.125rem}body,html{height:100%}.skip-to-content,body,html{background:var(--color-background-primary);color:var(--color-foreground-primary)}.skip-to-content{border-radius:1rem;left:.25rem;padding:1rem;position:fixed;top:.25rem;transform:translateY(-200%);transition:transform .3s ease-in-out;z-index:40}.skip-to-content:focus-within{transform:translateY(0)}article{background:var(--color-content-background);color:var(--color-content-foreground);overflow-wrap:break-word}.page{display:flex;min-height:100%}.mobile-header{background-color:var(--color-header-background);border-bottom:1px solid var(--color-header-border);color:var(--color-header-text);display:none;height:var(--header-height);width:100%;z-index:10}.mobile-header.scrolled{border-bottom:none;box-shadow:0 0 .2rem rgba(0,0,0,.1),0 .2rem .4rem rgba(0,0,0,.2)}.mobile-header .header-center a{color:var(--color-header-text);text-decoration:none}.main{display:flex;flex:1}.sidebar-drawer{background:var(--color-sidebar-background);border-right:1px solid var(--color-sidebar-background-border);box-sizing:border-box;display:flex;justify-content:flex-end;min-width:15em;width:calc(50% - 26em)}.sidebar-container,.toc-drawer{box-sizing:border-box;width:15em}.toc-drawer{background:var(--color-toc-background);padding-right:1rem}.sidebar-sticky,.toc-sticky{display:flex;flex-direction:column;height:min(100%,100vh);height:100vh;position:sticky;top:0}.sidebar-scroll,.toc-scroll{flex-grow:1;flex-shrink:1;overflow:auto;scroll-behavior:smooth}.content{display:flex;flex-direction:column;justify-content:space-between;padding:0 3em;width:46em}.icon{display:inline-block;height:1rem;width:1rem}.icon svg{height:100%;width:100%}.announcement{align-items:center;background-color:var(--color-announcement-background);color:var(--color-announcement-text);display:flex;height:var(--header-height);overflow-x:auto}.announcement+.page{min-height:calc(100% - var(--header-height))}.announcement-content{box-sizing:border-box;min-width:100%;padding:.5rem;text-align:center;white-space:nowrap}.announcement-content a{color:var(--color-announcement-text);text-decoration-color:var(--color-announcement-text)}.announcement-content a:hover{color:var(--color-announcement-text);text-decoration-color:var(--color-link--hover)}.no-js .theme-toggle-container{display:none}.theme-toggle-container{display:flex}.theme-toggle{background:transparent;border:none;cursor:pointer;display:flex;padding:0}.theme-toggle svg{color:var(--color-foreground-primary);display:none;height:1.25rem;width:1.25rem}.theme-toggle-header{align-items:center;display:flex;justify-content:center}.nav-overlay-icon,.toc-overlay-icon{cursor:pointer;display:none}.nav-overlay-icon .icon,.toc-overlay-icon .icon{color:var(--color-foreground-secondary);height:1.5rem;width:1.5rem}.nav-overlay-icon,.toc-header-icon{align-items:center;justify-content:center}.toc-content-icon{height:1.5rem;width:1.5rem}.content-icon-container{display:flex;float:right;gap:.5rem;margin-bottom:1rem;margin-left:1rem;margin-top:1.5rem}.content-icon-container .edit-this-page svg,.content-icon-container .view-this-page svg{color:inherit;height:1.25rem;width:1.25rem}.sidebar-toggle{display:none;position:absolute}.sidebar-toggle[name=__toc]{left:20px}.sidebar-toggle:checked{left:40px}.overlay{background-color:rgba(0,0,0,.54);height:0;opacity:0;position:fixed;top:0;transition:width 0ms,height 0ms,opacity .25s ease-out;width:0}.sidebar-overlay{z-index:20}.toc-overlay{z-index:40}.sidebar-drawer{transition:left .25s ease-in-out;z-index:30}.toc-drawer{transition:right .25s ease-in-out;z-index:50}#__navigation:checked~.sidebar-overlay{height:100%;opacity:1;width:100%}#__navigation:checked~.page .sidebar-drawer{left:0;top:0}#__toc:checked~.toc-overlay{height:100%;opacity:1;width:100%}#__toc:checked~.page .toc-drawer{right:0;top:0}.back-to-top{background:var(--color-background-primary);border-radius:1rem;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 1px 0 hsla(220,9%,46%,.502);display:none;font-size:.8125rem;left:0;margin-left:50%;padding:.5rem .75rem .5rem .5rem;position:fixed;text-decoration:none;top:1rem;transform:translateX(-50%);z-index:10}.back-to-top svg{height:1rem;width:1rem;fill:currentColor;display:inline-block}.back-to-top span{margin-left:.25rem}.show-back-to-top .back-to-top{align-items:center;display:flex}@media(min-width:97em){html{font-size:110%}}@media(max-width:82em){.toc-content-icon{display:flex}.toc-drawer{border-left:1px solid var(--color-background-muted);height:100vh;position:fixed;right:-15em;top:0}.toc-tree{border-left:none;font-size:var(--toc-font-size--mobile)}.sidebar-drawer{width:calc(50% - 18.5em)}}@media(max-width:67em){.content{margin-left:auto;margin-right:auto;padding:0 1em}}@media(max-width:63em){.nav-overlay-icon{display:flex}.sidebar-drawer{height:100vh;left:-15em;position:fixed;top:0;width:15em}.theme-toggle-header,.toc-header-icon{display:flex}.theme-toggle-content,.toc-content-icon{display:none}.mobile-header{align-items:center;display:flex;justify-content:space-between;position:sticky;top:0}.mobile-header .header-left,.mobile-header .header-right{display:flex;height:var(--header-height);padding:0 var(--header-padding)}.mobile-header .header-left label,.mobile-header .header-right label{height:100%;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:100%}.nav-overlay-icon .icon,.theme-toggle svg{height:1.5rem;width:1.5rem}:target{scroll-margin-top:calc(var(--header-height) + 2.5rem)}.back-to-top{top:calc(var(--header-height) + .5rem)}.page{flex-direction:column;justify-content:center}}@media(max-width:48em){.content{overflow-x:auto;width:100%}}@media(max-width:46em){article[role=main] aside.sidebar{float:none;margin:1rem 0;width:100%}}.admonition,.topic{background:var(--color-admonition-background);border-radius:.2rem;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1);font-size:var(--admonition-font-size);margin:1rem auto;overflow:hidden;padding:0 .5rem .5rem;page-break-inside:avoid}.admonition>:nth-child(2),.topic>:nth-child(2){margin-top:0}.admonition>:last-child,.topic>:last-child{margin-bottom:0}.admonition p.admonition-title,p.topic-title{font-size:var(--admonition-title-font-size);font-weight:500;line-height:1.3;margin:0 -.5rem .5rem;padding:.4rem .5rem .4rem 2rem;position:relative}.admonition p.admonition-title:before,p.topic-title:before{content:"";height:1rem;left:.5rem;position:absolute;width:1rem}p.admonition-title{background-color:var(--color-admonition-title-background)}p.admonition-title:before{background-color:var(--color-admonition-title);-webkit-mask-image:var(--icon-admonition-default);mask-image:var(--icon-admonition-default);-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat}p.topic-title{background-color:var(--color-topic-title-background)}p.topic-title:before{background-color:var(--color-topic-title);-webkit-mask-image:var(--icon-topic-default);mask-image:var(--icon-topic-default);-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat}.admonition{border-left:.2rem solid var(--color-admonition-title)}.admonition.caution{border-left-color:var(--color-admonition-title--caution)}.admonition.caution>.admonition-title{background-color:var(--color-admonition-title-background--caution)}.admonition.caution>.admonition-title:before{background-color:var(--color-admonition-title--caution);-webkit-mask-image:var(--icon-spark);mask-image:var(--icon-spark)}.admonition.warning{border-left-color:var(--color-admonition-title--warning)}.admonition.warning>.admonition-title{background-color:var(--color-admonition-title-background--warning)}.admonition.warning>.admonition-title:before{background-color:var(--color-admonition-title--warning);-webkit-mask-image:var(--icon-warning);mask-image:var(--icon-warning)}.admonition.danger{border-left-color:var(--color-admonition-title--danger)}.admonition.danger>.admonition-title{background-color:var(--color-admonition-title-background--danger)}.admonition.danger>.admonition-title:before{background-color:var(--color-admonition-title--danger);-webkit-mask-image:var(--icon-spark);mask-image:var(--icon-spark)}.admonition.attention{border-left-color:var(--color-admonition-title--attention)}.admonition.attention>.admonition-title{background-color:var(--color-admonition-title-background--attention)}.admonition.attention>.admonition-title:before{background-color:var(--color-admonition-title--attention);-webkit-mask-image:var(--icon-warning);mask-image:var(--icon-warning)}.admonition.error{border-left-color:var(--color-admonition-title--error)}.admonition.error>.admonition-title{background-color:var(--color-admonition-title-background--error)}.admonition.error>.admonition-title:before{background-color:var(--color-admonition-title--error);-webkit-mask-image:var(--icon-failure);mask-image:var(--icon-failure)}.admonition.hint{border-left-color:var(--color-admonition-title--hint)}.admonition.hint>.admonition-title{background-color:var(--color-admonition-title-background--hint)}.admonition.hint>.admonition-title:before{background-color:var(--color-admonition-title--hint);-webkit-mask-image:var(--icon-question);mask-image:var(--icon-question)}.admonition.tip{border-left-color:var(--color-admonition-title--tip)}.admonition.tip>.admonition-title{background-color:var(--color-admonition-title-background--tip)}.admonition.tip>.admonition-title:before{background-color:var(--color-admonition-title--tip);-webkit-mask-image:var(--icon-info);mask-image:var(--icon-info)}.admonition.important{border-left-color:var(--color-admonition-title--important)}.admonition.important>.admonition-title{background-color:var(--color-admonition-title-background--important)}.admonition.important>.admonition-title:before{background-color:var(--color-admonition-title--important);-webkit-mask-image:var(--icon-flame);mask-image:var(--icon-flame)}.admonition.note{border-left-color:var(--color-admonition-title--note)}.admonition.note>.admonition-title{background-color:var(--color-admonition-title-background--note)}.admonition.note>.admonition-title:before{background-color:var(--color-admonition-title--note);-webkit-mask-image:var(--icon-pencil);mask-image:var(--icon-pencil)}.admonition.seealso{border-left-color:var(--color-admonition-title--seealso)}.admonition.seealso>.admonition-title{background-color:var(--color-admonition-title-background--seealso)}.admonition.seealso>.admonition-title:before{background-color:var(--color-admonition-title--seealso);-webkit-mask-image:var(--icon-info);mask-image:var(--icon-info)}.admonition.admonition-todo{border-left-color:var(--color-admonition-title--admonition-todo)}.admonition.admonition-todo>.admonition-title{background-color:var(--color-admonition-title-background--admonition-todo)}.admonition.admonition-todo>.admonition-title:before{background-color:var(--color-admonition-title--admonition-todo);-webkit-mask-image:var(--icon-pencil);mask-image:var(--icon-pencil)}.admonition-todo>.admonition-title{text-transform:uppercase}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd{margin-left:2rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd>:first-child{margin-top:.125rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list,dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd>:last-child{margin-bottom:.75rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list>dt{font-size:var(--font-size--small);text-transform:uppercase}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd:empty{margin-bottom:.5rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul{margin-left:-1.2rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul>li>p:nth-child(2){margin-top:0}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul>li>p+p:last-child:empty{margin-bottom:0;margin-top:0}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt{color:var(--color-api-overall)}.sig:not(.sig-inline){background:var(--color-api-background);border-radius:.25rem;font-family:var(--font-stack--monospace);font-size:var(--api-font-size);font-weight:700;margin-left:-.25rem;margin-right:-.25rem;padding:.25rem .5rem .25rem 3em;text-indent:-2.5em;transition:background .1s ease-out}.sig:not(.sig-inline):hover{background:var(--color-api-background-hover)}.sig:not(.sig-inline) a.reference .viewcode-link{font-weight:400;width:4.25rem}em.property{font-style:normal}em.property:first-child{color:var(--color-api-keyword)}.sig-name{color:var(--color-api-name)}.sig-prename{color:var(--color-api-pre-name);font-weight:400}.sig-paren{color:var(--color-api-paren)}.sig-param{font-style:normal}div.deprecated,div.versionadded,div.versionchanged,div.versionremoved{border-left:.1875rem solid;border-radius:.125rem;padding-left:.75rem}div.deprecated p,div.versionadded p,div.versionchanged p,div.versionremoved p{margin-bottom:.125rem;margin-top:.125rem}div.versionadded{border-color:var(--color-api-added-border)}div.versionadded .versionmodified{color:var(--color-api-added)}div.versionchanged{border-color:var(--color-api-changed-border)}div.versionchanged .versionmodified{color:var(--color-api-changed)}div.deprecated{border-color:var(--color-api-deprecated-border)}div.deprecated .versionmodified{color:var(--color-api-deprecated)}div.versionremoved{border-color:var(--color-api-removed-border)}div.versionremoved .versionmodified{color:var(--color-api-removed)}.viewcode-back,.viewcode-link{float:right;text-align:right}.line-block{margin-bottom:.75rem;margin-top:.5rem}.line-block .line-block{margin-bottom:0;margin-top:0;padding-left:1rem}.code-block-caption,article p.caption,table>caption{font-size:var(--font-size--small);text-align:center}.toctree-wrapper.compound .caption,.toctree-wrapper.compound :not(.caption)>.caption-text{font-size:var(--font-size--small);margin-bottom:0;text-align:initial;text-transform:uppercase}.toctree-wrapper.compound>ul{margin-bottom:0;margin-top:0}.sig-inline,code.literal{background:var(--color-inline-code-background);border-radius:.2em;font-size:var(--font-size--small--2);padding:.1em .2em}pre.literal-block .sig-inline,pre.literal-block code.literal{font-size:inherit;padding:0}p .sig-inline,p code.literal{border:1px solid var(--color-background-border)}.sig-inline{font-family:var(--font-stack--monospace)}div[class*=" highlight-"],div[class^=highlight-]{display:flex;margin:1em 0}div[class*=" highlight-"] .table-wrapper,div[class^=highlight-] .table-wrapper,pre{margin:0;padding:0}pre{overflow:auto}article[role=main] .highlight pre{line-height:1.5}.highlight pre,pre.literal-block{font-size:var(--code-font-size);padding:.625rem .875rem}pre.literal-block{background-color:var(--color-code-background);border-radius:.2rem;color:var(--color-code-foreground);margin-bottom:1rem;margin-top:1rem}.highlight{border-radius:.2rem;width:100%}.highlight .gp,.highlight span.linenos{pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.highlight .hll{display:block;margin-left:-.875rem;margin-right:-.875rem;padding-left:.875rem;padding-right:.875rem}.code-block-caption{background-color:var(--color-code-background);border-bottom:1px solid;border-radius:.25rem;border-bottom-left-radius:0;border-bottom-right-radius:0;border-color:var(--color-background-border);color:var(--color-code-foreground);display:flex;font-weight:300;padding:.625rem .875rem}.code-block-caption+div[class]{margin-top:0}.code-block-caption+div[class] pre{border-top-left-radius:0;border-top-right-radius:0}.highlighttable{display:block;width:100%}.highlighttable tbody{display:block}.highlighttable tr{display:flex}.highlighttable td.linenos{background-color:var(--color-code-background);border-bottom-left-radius:.2rem;border-top-left-radius:.2rem;color:var(--color-code-foreground);padding:.625rem 0 .625rem .875rem}.highlighttable .linenodiv{box-shadow:-.0625rem 0 var(--color-foreground-border) inset;font-size:var(--code-font-size);padding-right:.875rem}.highlighttable td.code{display:block;flex:1;overflow:hidden;padding:0}.highlighttable td.code .highlight{border-bottom-left-radius:0;border-top-left-radius:0}.highlight span.linenos{box-shadow:-.0625rem 0 var(--color-foreground-border) inset;display:inline-block;margin-right:.875rem;padding-left:0;padding-right:.875rem}.footnote-reference{font-size:var(--font-size--small--4);vertical-align:super}dl.footnote.brackets{color:var(--color-foreground-secondary);display:grid;font-size:var(--font-size--small);grid-template-columns:max-content auto}dl.footnote.brackets dt{margin:0}dl.footnote.brackets dt>.fn-backref{margin-left:.25rem}dl.footnote.brackets dt:after{content:":"}dl.footnote.brackets dt .brackets:before{content:"["}dl.footnote.brackets dt .brackets:after{content:"]"}dl.footnote.brackets dd{margin:0;padding:0 1rem}aside.footnote{color:var(--color-foreground-secondary);font-size:var(--font-size--small)}aside.footnote>span,div.citation>span{float:left;font-weight:500;padding-right:.25rem}aside.footnote>:not(span),div.citation>p{margin-left:2rem}img{box-sizing:border-box;height:auto;max-width:100%}article .figure,article figure{border-radius:.2rem;margin:0}article .figure :last-child,article figure :last-child{margin-bottom:0}article .align-left{clear:left;float:left;margin:0 1rem 1rem}article .align-right{clear:right;float:right;margin:0 1rem 1rem}article .align-center,article .align-default{display:block;margin-left:auto;margin-right:auto;text-align:center}article table.align-default{display:table;text-align:initial}.domainindex-jumpbox,.genindex-jumpbox{border-bottom:1px solid var(--color-background-border);border-top:1px solid var(--color-background-border);padding:.25rem}.domainindex-section h2,.genindex-section h2{margin-bottom:.5rem;margin-top:.75rem}.domainindex-section ul,.genindex-section ul{margin-bottom:0;margin-top:0}ol,ul{margin-bottom:1rem;margin-top:1rem;padding-left:1.2rem}ol li>p:first-child,ul li>p:first-child{margin-bottom:.25rem;margin-top:.25rem}ol li>p:last-child,ul li>p:last-child{margin-top:.25rem}ol li>ol,ol li>ul,ul li>ol,ul li>ul{margin-bottom:.5rem;margin-top:.5rem}ol.arabic{list-style:decimal}ol.loweralpha{list-style:lower-alpha}ol.upperalpha{list-style:upper-alpha}ol.lowerroman{list-style:lower-roman}ol.upperroman{list-style:upper-roman}.simple li>ol,.simple li>ul,.toctree-wrapper li>ol,.toctree-wrapper li>ul{margin-bottom:0;margin-top:0}.field-list dt,.option-list dt,dl.footnote dt,dl.glossary dt,dl.simple dt,dl:not([class]) dt{font-weight:500;margin-top:.25rem}.field-list dt+dt,.option-list dt+dt,dl.footnote dt+dt,dl.glossary dt+dt,dl.simple dt+dt,dl:not([class]) dt+dt{margin-top:0}.field-list dt .classifier:before,.option-list dt .classifier:before,dl.footnote dt .classifier:before,dl.glossary dt .classifier:before,dl.simple dt .classifier:before,dl:not([class]) dt .classifier:before{content:":";margin-left:.2rem;margin-right:.2rem}.field-list dd ul,.field-list dd>p:first-child,.option-list dd ul,.option-list dd>p:first-child,dl.footnote dd ul,dl.footnote dd>p:first-child,dl.glossary dd ul,dl.glossary dd>p:first-child,dl.simple dd ul,dl.simple dd>p:first-child,dl:not([class]) dd ul,dl:not([class]) dd>p:first-child{margin-top:.125rem}.field-list dd ul,.option-list dd ul,dl.footnote dd ul,dl.glossary dd ul,dl.simple dd ul,dl:not([class]) dd ul{margin-bottom:.125rem}.math-wrapper{overflow-x:auto;width:100%}div.math{position:relative;text-align:center}div.math .headerlink,div.math:focus .headerlink{display:none}div.math:hover .headerlink{display:inline-block}div.math span.eqno{position:absolute;right:.5rem;top:50%;transform:translateY(-50%);z-index:1}abbr[title]{cursor:help}.problematic{color:var(--color-problematic)}kbd:not(.compound){background-color:var(--color-background-secondary);border:1px solid var(--color-foreground-border);border-radius:.2rem;box-shadow:0 .0625rem 0 rgba(0,0,0,.2),inset 0 0 0 .125rem var(--color-background-primary);color:var(--color-foreground-primary);display:inline-block;font-size:var(--font-size--small--3);margin:0 .2rem;padding:0 .2rem;vertical-align:text-bottom}blockquote{background:var(--color-background-secondary);border-left:4px solid var(--color-background-border);margin-left:0;margin-right:0;padding:.5rem 1rem}blockquote .attribution{font-weight:600;text-align:right}blockquote.highlights,blockquote.pull-quote{font-size:1.25em}blockquote.epigraph,blockquote.pull-quote{border-left-width:0;border-radius:.5rem}blockquote.highlights{background:transparent;border-left-width:0}p .reference img{vertical-align:middle}p.rubric{font-size:1.125em;font-weight:700;line-height:1.25}dd p.rubric{font-size:var(--font-size--small);font-weight:inherit;line-height:inherit;text-transform:uppercase}article .sidebar{background-color:var(--color-background-secondary);border:1px solid var(--color-background-border);border-radius:.2rem;clear:right;float:right;margin-left:1rem;margin-right:0;width:30%}article .sidebar>*{padding-left:1rem;padding-right:1rem}article .sidebar>ol,article .sidebar>ul{padding-left:2.2rem}article .sidebar .sidebar-title{border-bottom:1px solid var(--color-background-border);font-weight:500;margin:0;padding:.5rem 1rem}[role=main] .table-wrapper.container{margin-bottom:.5rem;margin-top:1rem;overflow-x:auto;padding:.2rem .2rem .75rem;width:100%}table.docutils{border-collapse:collapse;border-radius:.2rem;border-spacing:0;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1)}table.docutils th{background:var(--color-table-header-background)}table.docutils td,table.docutils th{border-bottom:1px solid var(--color-table-border);border-left:1px solid var(--color-table-border);border-right:1px solid var(--color-table-border);padding:0 .25rem}table.docutils td p,table.docutils th p{margin:.25rem}table.docutils td:first-child,table.docutils th:first-child{border-left:none}table.docutils td:last-child,table.docutils th:last-child{border-right:none}table.docutils td.text-left,table.docutils th.text-left{text-align:left}table.docutils td.text-right,table.docutils th.text-right{text-align:right}table.docutils td.text-center,table.docutils th.text-center{text-align:center}:target{scroll-margin-top:2.5rem}@media(max-width:67em){:target{scroll-margin-top:calc(2.5rem + var(--header-height))}section>span:target{scroll-margin-top:calc(2.8rem + var(--header-height))}}.headerlink{font-weight:100;-webkit-user-select:none;-moz-user-select:none;user-select:none}.code-block-caption>.headerlink,dl dt>.headerlink,figcaption p>.headerlink,h1>.headerlink,h2>.headerlink,h3>.headerlink,h4>.headerlink,h5>.headerlink,h6>.headerlink,p.caption>.headerlink,table>caption>.headerlink{margin-left:.5rem;visibility:hidden}.code-block-caption:hover>.headerlink,dl dt:hover>.headerlink,figcaption p:hover>.headerlink,h1:hover>.headerlink,h2:hover>.headerlink,h3:hover>.headerlink,h4:hover>.headerlink,h5:hover>.headerlink,h6:hover>.headerlink,p.caption:hover>.headerlink,table>caption:hover>.headerlink{visibility:visible}.code-block-caption>.toc-backref,dl dt>.toc-backref,figcaption p>.toc-backref,h1>.toc-backref,h2>.toc-backref,h3>.toc-backref,h4>.toc-backref,h5>.toc-backref,h6>.toc-backref,p.caption>.toc-backref,table>caption>.toc-backref{color:inherit;text-decoration-line:none}figure:hover>figcaption>p>.headerlink,table:hover>caption>.headerlink{visibility:visible}:target>h1:first-of-type,:target>h2:first-of-type,:target>h3:first-of-type,:target>h4:first-of-type,:target>h5:first-of-type,:target>h6:first-of-type,span:target~h1:first-of-type,span:target~h2:first-of-type,span:target~h3:first-of-type,span:target~h4:first-of-type,span:target~h5:first-of-type,span:target~h6:first-of-type{background-color:var(--color-highlight-on-target)}:target>h1:first-of-type code.literal,:target>h2:first-of-type code.literal,:target>h3:first-of-type code.literal,:target>h4:first-of-type code.literal,:target>h5:first-of-type code.literal,:target>h6:first-of-type code.literal,span:target~h1:first-of-type code.literal,span:target~h2:first-of-type code.literal,span:target~h3:first-of-type code.literal,span:target~h4:first-of-type code.literal,span:target~h5:first-of-type code.literal,span:target~h6:first-of-type code.literal{background-color:transparent}.literal-block-wrapper:target .code-block-caption,.this-will-duplicate-information-and-it-is-still-useful-here li :target,figure:target,table:target>caption{background-color:var(--color-highlight-on-target)}dt:target{background-color:var(--color-highlight-on-target)!important}.footnote-reference:target,.footnote>dt:target+dd{background-color:var(--color-highlight-on-target)}.guilabel{background-color:var(--color-guilabel-background);border:1px solid var(--color-guilabel-border);border-radius:.5em;color:var(--color-guilabel-text);font-size:.9em;padding:0 .3em}footer{display:flex;flex-direction:column;font-size:var(--font-size--small);margin-top:2rem}.bottom-of-page{align-items:center;border-top:1px solid var(--color-background-border);color:var(--color-foreground-secondary);display:flex;justify-content:space-between;line-height:1.5;margin-top:1rem;padding-bottom:1rem;padding-top:1rem}@media(max-width:46em){.bottom-of-page{flex-direction:column-reverse;gap:.25rem;text-align:center}}.bottom-of-page .left-details{font-size:var(--font-size--small)}.bottom-of-page .right-details{display:flex;flex-direction:column;gap:.25rem;text-align:right}.bottom-of-page .icons{display:flex;font-size:1rem;gap:.25rem;justify-content:flex-end}.bottom-of-page .icons a{text-decoration:none}.bottom-of-page .icons img,.bottom-of-page .icons svg{font-size:1.125rem;height:1em;width:1em}.related-pages a{align-items:center;display:flex;text-decoration:none}.related-pages a:hover .page-info .title{color:var(--color-link);text-decoration:underline;text-decoration-color:var(--color-link-underline)}.related-pages a svg.furo-related-icon,.related-pages a svg.furo-related-icon>use{color:var(--color-foreground-border);flex-shrink:0;height:.75rem;margin:0 .5rem;width:.75rem}.related-pages a.next-page{clear:right;float:right;max-width:50%;text-align:right}.related-pages a.prev-page{clear:left;float:left;max-width:50%}.related-pages a.prev-page svg{transform:rotate(180deg)}.page-info{display:flex;flex-direction:column;overflow-wrap:anywhere}.next-page .page-info{align-items:flex-end}.page-info .context{align-items:center;color:var(--color-foreground-muted);display:flex;font-size:var(--font-size--small);padding-bottom:.1rem;text-decoration:none}ul.search{list-style:none;padding-left:0}ul.search li{border-bottom:1px solid var(--color-background-border);padding:1rem 0}[role=main] .highlighted{background-color:var(--color-highlighted-background);color:var(--color-highlighted-text)}.sidebar-brand{display:flex;flex-direction:column;flex-shrink:0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-decoration:none}.sidebar-brand-text{color:var(--color-sidebar-brand-text);font-size:1.5rem;overflow-wrap:break-word}.sidebar-brand-text,.sidebar-logo-container{margin:var(--sidebar-item-spacing-vertical) 0}.sidebar-logo{display:block;margin:0 auto;max-width:100%}.sidebar-search-container{align-items:center;background:var(--color-sidebar-search-background);display:flex;margin-top:var(--sidebar-search-space-above);position:relative}.sidebar-search-container:focus-within,.sidebar-search-container:hover{background:var(--color-sidebar-search-background--focus)}.sidebar-search-container:before{background-color:var(--color-sidebar-search-icon);content:"";height:var(--sidebar-search-icon-size);left:var(--sidebar-item-spacing-horizontal);-webkit-mask-image:var(--icon-search);mask-image:var(--icon-search);position:absolute;width:var(--sidebar-search-icon-size)}.sidebar-search{background:transparent;border:none;border-bottom:1px solid var(--color-sidebar-search-border);border-top:1px solid var(--color-sidebar-search-border);box-sizing:border-box;color:var(--color-sidebar-search-foreground);padding:var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal) var(--sidebar-search-input-spacing-vertical) calc(var(--sidebar-item-spacing-horizontal) + var(--sidebar-search-input-spacing-horizontal) + var(--sidebar-search-icon-size));width:100%;z-index:10}.sidebar-search:focus{outline:none}.sidebar-search::-moz-placeholder{font-size:var(--sidebar-search-input-font-size)}.sidebar-search::placeholder{font-size:var(--sidebar-search-input-font-size)}#searchbox .highlight-link{margin:0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0;text-align:center}#searchbox .highlight-link a{color:var(--color-sidebar-search-icon);font-size:var(--font-size--small--2)}.sidebar-tree{font-size:var(--sidebar-item-font-size);margin-bottom:var(--sidebar-item-spacing-vertical);margin-top:var(--sidebar-tree-space-above)}.sidebar-tree ul{display:flex;flex-direction:column;list-style:none;margin-bottom:0;margin-top:0;padding:0}.sidebar-tree li{margin:0;position:relative}.sidebar-tree li>ul{margin-left:var(--sidebar-item-spacing-horizontal)}.sidebar-tree .icon,.sidebar-tree .reference{color:var(--color-sidebar-link-text)}.sidebar-tree .reference{box-sizing:border-box;display:inline-block;height:100%;line-height:var(--sidebar-item-line-height);overflow-wrap:anywhere;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-decoration:none;width:100%}.sidebar-tree .reference:hover{background:var(--color-sidebar-item-background--hover);color:var(--color-sidebar-link-text)}.sidebar-tree .reference.external:after{color:var(--color-sidebar-link-text);content:url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' fill='none' stroke='%23607D8B' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.5' viewBox='0 0 24 24'%3E%3Cpath stroke='none' d='M0 0h24v24H0z'/%3E%3Cpath d='M11 7H6a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h9a2 2 0 0 0 2-2v-5M10 14 20 4M15 4h5v5'/%3E%3C/svg%3E");margin:0 .25rem;vertical-align:middle}.sidebar-tree .current-page>.reference{font-weight:700}.sidebar-tree label{align-items:center;cursor:pointer;display:flex;height:var(--sidebar-item-height);justify-content:center;position:absolute;right:0;top:0;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:var(--sidebar-expander-width)}.sidebar-tree .caption,.sidebar-tree :not(.caption)>.caption-text{color:var(--color-sidebar-caption-text);font-size:var(--sidebar-caption-font-size);font-weight:700;margin:var(--sidebar-caption-space-above) 0 0 0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-transform:uppercase}.sidebar-tree li.has-children>.reference{padding-right:var(--sidebar-expander-width)}.sidebar-tree .toctree-l1>.reference,.sidebar-tree .toctree-l1>label .icon{color:var(--color-sidebar-link-text--top-level)}.sidebar-tree label{background:var(--color-sidebar-item-expander-background)}.sidebar-tree label:hover{background:var(--color-sidebar-item-expander-background--hover)}.sidebar-tree .current>.reference{background:var(--color-sidebar-item-background--current)}.sidebar-tree .current>.reference:hover{background:var(--color-sidebar-item-background--hover)}.toctree-checkbox{display:none;position:absolute}.toctree-checkbox~ul{display:none}.toctree-checkbox~label .icon svg{transform:rotate(90deg)}.toctree-checkbox:checked~ul{display:block}.toctree-checkbox:checked~label .icon svg{transform:rotate(-90deg)}.toc-title-container{padding:var(--toc-title-padding);padding-top:var(--toc-spacing-vertical)}.toc-title{color:var(--color-toc-title-text);font-size:var(--toc-title-font-size);padding-left:var(--toc-spacing-horizontal);text-transform:uppercase}.no-toc{display:none}.toc-tree-container{padding-bottom:var(--toc-spacing-vertical)}.toc-tree{border-left:1px solid var(--color-background-border);font-size:var(--toc-font-size);line-height:1.3;padding-left:calc(var(--toc-spacing-horizontal) - var(--toc-item-spacing-horizontal))}.toc-tree>ul>li:first-child{padding-top:0}.toc-tree>ul>li:first-child>ul{padding-left:0}.toc-tree>ul>li:first-child>a{display:none}.toc-tree ul{list-style-type:none;margin-bottom:0;margin-top:0;padding-left:var(--toc-item-spacing-horizontal)}.toc-tree li{padding-top:var(--toc-item-spacing-vertical)}.toc-tree li.scroll-current>.reference{color:var(--color-toc-item-text--active);font-weight:700}.toc-tree a.reference{color:var(--color-toc-item-text);overflow-wrap:anywhere;text-decoration:none}.toc-scroll{max-height:100vh;overflow-y:scroll}.contents:not(.this-will-duplicate-information-and-it-is-still-useful-here){background:rgba(255,0,0,.25);color:var(--color-problematic)}.contents:not(.this-will-duplicate-information-and-it-is-still-useful-here):before{content:"ERROR: Adding a table of contents in Furo-based documentation is unnecessary, and does not work well with existing styling. Add a 'this-will-duplicate-information-and-it-is-still-useful-here' class, if you want an escape hatch."}.text-align\:left>p{text-align:left}.text-align\:center>p{text-align:center}.text-align\:right>p{text-align:right} +/*# sourceMappingURL=furo.css.map*/ \ No newline at end of file diff --git a/_static/styles/furo.css.map b/_static/styles/furo.css.map new file mode 100644 index 00000000..3ecc3715 --- /dev/null +++ b/_static/styles/furo.css.map @@ -0,0 +1 @@ +{"version":3,"file":"styles/furo.css","mappings":"AAAA,2EAA2E,CAU3E,KACE,gBAAiB,CACjB,6BACF,CASA,KACE,QACF,CAMA,KACE,aACF,CAOA,GACE,aAAc,CACd,cACF,CAUA,GACE,sBAAuB,CACvB,QAAS,CACT,gBACF,CAOA,IACE,+BAAiC,CACjC,aACF,CASA,EACE,4BACF,CAOA,YACE,kBAAmB,CACnB,yBAA0B,CAC1B,gCACF,CAMA,SAEE,kBACF,CAOA,cAGE,+BAAiC,CACjC,aACF,CAeA,QAEE,aAAc,CACd,aAAc,CACd,iBAAkB,CAClB,uBACF,CAEA,IACE,aACF,CAEA,IACE,SACF,CASA,IACE,iBACF,CAUA,sCAKE,mBAAoB,CACpB,cAAe,CACf,gBAAiB,CACjB,QACF,CAOA,aAEE,gBACF,CAOA,cAEE,mBACF,CAMA,gDAIE,yBACF,CAMA,wHAIE,iBAAkB,CAClB,SACF,CAMA,4GAIE,6BACF,CAMA,SACE,0BACF,CASA,OACE,qBAAsB,CACtB,aAAc,CACd,aAAc,CACd,cAAe,CACf,SAAU,CACV,kBACF,CAMA,SACE,uBACF,CAMA,SACE,aACF,CAOA,6BAEE,qBAAsB,CACtB,SACF,CAMA,kFAEE,WACF,CAOA,cACE,4BAA6B,CAC7B,mBACF,CAMA,yCACE,uBACF,CAOA,6BACE,yBAA0B,CAC1B,YACF,CASA,QACE,aACF,CAMA,QACE,iBACF,CAiBA,kBACE,YACF,CCvVA,aAcE,kEACE,uBAOF,WACE,iDAMF,kCACE,wBAEF,qCAEE,uBADA,uBACA,CAEF,SACE,wBAtBA,CCpBJ,iBAGE,qBAEA,sBACA,0BAFA,oBAHA,4BACA,oBAKA,6BAIA,2CAFA,mBACA,sCAFA,4BAGA,CAEF,gBACE,aCTF,KCGE,mHAEA,wGAEA,wCAAyC,CAEzC,wBAAyB,CACzB,wBAAyB,CACzB,4BAA6B,CAC7B,yBAA0B,CAC1B,2BAA4B,CAG5B,sDAAuD,CACvD,gDAAiD,CACjD,wDAAyD,CAGzD,0CAA2C,CAC3C,gDAAiD,CACjD,gDAAiD,CAKjD,gCAAiC,CACjC,sCAAuC,CAGvC,2CAA4C,CAG5C,uCAAwC,CCjCxC,+FAGA,uBAAwB,CAGxB,iCAAkC,CAClC,kCAAmC,CAEnC,+BAAgC,CAChC,sCAAuC,CACvC,sCAAuC,CACvC,qGAIA,mDAAoD,CAEpD,mCAAoC,CACpC,8CAA+C,CAC/C,gDAAiD,CACjD,kCAAmC,CACnC,6DAA8D,CAG9D,6BAA8B,CAC9B,6BAA8B,CAC9B,+BAAgC,CAChC,kCAAmC,CACnC,kCAAmC,CCPjC,+jBCYA,iqCAZF,iaCVA,8KAOA,4SAWA,4SAUA,0CACA,gEAGA,0CAGA,gEAGA,yCACA,+DAIA,4CACA,kEAGA,wCAUA,8DACA,uCAGA,4DACA,sCACA,2DAGA,4CACA,kEACA,uCAGA,6DACA,2GAGA,sHAEA,yFAEA,+CACA,+EAGA,4MAOA,gCACA,sHAIA,kCACA,uEACA,gEACA,4DACA,kEAGA,2DACA,sDACA,0CACA,8CACA,wGAGA,0BACA,iCAGA,+DACA,+BACA,sCACA,+DAEA,kGACA,oCACA,yDACA,sCL7HF,kCAEA,sDAIA,0CK2HE,kEAIA,oDACA,sDAGA,oCACA,oEAEA,0DACA,qDAIA,oDACA,6DAIA,iEAIA,2DAIA,2DAGA,4DACA,gEAIA,gEAEA,gFAEA,oNASA,qDLxKE,gFAGE,4DAIF,oEKkHF,yEAEA,6DAGA,0DAEA,uDACA,qDACA,wDAIA,6DAIA,yDACA,2DAIA,uCAGA,wCACA,sDAGA,+CAGA,6DAEA,iDACA,+DAEA,wDAEA,sEAMA,0DACA,sBACA,mEL9JI,wEAEA,iCACE,+BAMN,wEAGA,iCACE,kFAEA,uEAIF,gEACE,8BAGF,qEMvDA,sCAKA,wFAKA,iCAIA,0BAWA,iCACA,4BACA,mCAGA,+BAEA,sCACA,4BAEA,mCAEA,sCAKA,sDAIA,gCAEA,gEAQF,wCAME,sBACA,kCAKA,uBAEA,gEAIA,2BAIA,mCAEA,qCACA,iCAGE,+BACA,wEAEE,iCACA,kFAGF,6BACA,0CACF,kCAEE,8BACE,8BACA,qEAEE,sCACA,wFCnFN,iCAGF,2DAEE,4BACA,oCAGA,mIAGA,4HACE,gEAMJ,+CAGE,sBACA,yCAEF,uBAEE,sEAKA,gDACA,kEAGA,iFAGE,YAGF,EACA,4HAQF,mBACE,6BACA,mBACA,wCACA,wCACA,2CAIA,eAGA,mBAKE,mBAGA,CAJA,uCACA,iBAFF,gBACE,CAKE,mBACA,mBAGJ,oBAIF,+BAGE,kDACA,OADA,kBAGA,CAFA,gBAEA,mBACA,oBAEA,sCACA,OAGF,cAHE,WAGF,GAEE,oBACA,CAHF,gBAGE,CC9Gc,YDiHd,+CAIF,SAEE,CAPF,UACE,wBAMA,4BAEA,GAGA,uBACA,CAJA,yBAGA,CACA,iDAKA,2CAGA,2DAQA,iBACA,uCAGA,kEAKE,SAKJ,8BACE,yDACA,2BAEA,oBACA,8BAEA,yDAEE,4BAEJ,uCACE,CACA,iEAGA,CAEA,wCACE,uBACA,kDAEA,0DAEE,CAJF,oBAIE,0GAWN,aACE,CAHA,YAGA,4HASA,+CAGF,sBACE,WACA,WAQA,4BAFF,0CAEE,CARA,qCAsBA,CAdA,iBAEA,kBACE,aADF,4BACE,WAMF,2BAGF,qCAEE,CAXE,UAWF,+BAGA,uBAEA,SAEA,0CAIE,CANF,qCAEA,CAIE,2DACE,gBAIN,+CAIA,CAEA,kDAKE,CAPF,8BAEA,CAOE,YACA,CAjBI,2BAGN,CAHM,WAcJ,UAGA,CAEA,2GAIF,iCAGE,8BAIA,qBACA,oBACF,uBAOI,0CAIA,CATF,6DAKE,CALF,sBASE,qCAKF,CACE,cACA,CAFF,sBAEE,CACA,+BAEA,qBAEE,WAKN,aACE,sCAGA,mBAEA,6BAMA,kCACA,CAJA,sBACA,aAEA,CAJA,eACA,MAIA,2FAEA,UAGA,YACA,sBACE,8BAEA,CALF,aACA,WAIE,OACA,oBAEF,uBACE,WAEF,YAFE,UAEF,eAgBA,kBACE,CAhBA,qDAQF,qCAGF,CAGI,YACF,CAJF,2BAGI,CAEA,eACA,qBAGA,mEAEA,qBACA,8BAIA,kBADF,kBACE,yBAEJ,oCAGI,qDAIJ,+BAGI,oCAEA,+CAQF,4CACE,yBACF,2BAOE,sBACA,CAHA,WACA,CAFF,cACE,CAJA,YAGF,CAEE,SAEA,mBAGA,kDAEE,CAJF,cAEA,cAEE,sBAEA,mBADA,YACA,uBACA,mDACE,CADF,YACE,iDAEA,uCAEN,+DAOE,mBADF,sBACE,mBAGF,aACE,sCAIA,aADF,WACE,CAKF,SACE,CAHJ,kBAEE,CAJE,gBAEJ,CAHI,iBAMA,yFAKA,aACA,eACA,cElbJ,iBAEE,aADA,iBACA,6BAEA,kCAEA,SACA,UAIA,gCACA,CALA,SAEA,SAEA,CAJA,0EAEA,CAFA,OAKA,CAGA,mDACE,iBAGF,gCACE,CADF,UACE,aAEJ,iCAEE,CAFF,UAEE,wCAEA,WACA,WADA,UACA,CACA,4CAGA,MACA,CADA,KACA,wCACA,UAGA,CAJA,UAIA,6DAUA,0CACE,CAFF,mBAEE,wEACA,CAVA,YACA,CAMF,mBAJE,OAOA,gBAJJ,gCACE,CANE,cACA,CAHA,oBACA,CAGA,QAGJ,CAII,0BACA,CADA,UACA,wCAEJ,kBACE,0DACA,gCACE,kBACA,CADA,YACA,oEACA,2CAMF,mDAII,CALN,YACE,CANE,cAKJ,CACE,iBAII,kEACA,yCACE,kDACA,yDACE,+CACA,uBANN,CAMM,+BANN,uCACE,qDACA,4BAEE,mBADA,0CACA,CADA,qBACA,0DACE,wCACA,sGALJ,oCACA,sBACE,kBAFF,UAEE,2CACA,wFACE,cACA,kEANN,uBACE,iDACA,CADA,UACA,0DACE,wDAEE,iEACA,qEANN,sCACE,CAGE,iBAHF,gBAGE,qBACE,CAJJ,uBACA,gDACE,wDACA,6DAHF,2CACA,CADA,gBACA,eACE,CAGE,sBANN,8BACE,CAII,iBAFF,4DACA,WACE,YADF,uCACE,6EACA,2BANN,8CACE,kDACA,0CACE,8BACA,yFACE,sBACA,sFALJ,mEACA,sBACE,kEACA,6EACE,uCACA,kEALJ,qGAEE,kEACA,6EACE,uCACA,kEALJ,8CACA,uDACE,sEACA,2EACE,sCACA,iEALJ,mGACA,qCACE,oDACA,0DACE,6GACA,gDAGR,yDCrEA,sEACE,CACA,6GACE,gEACF,iGAIF,wFACE,qDAGA,mGAEE,2CAEF,4FACE,gCACF,wGACE,8DAEE,6FAIA,iJAKN,6GACE,gDAKF,yDACA,qCAGA,6BACA,kBACA,qDAKA,oCAEA,+DAGA,2CAGE,oDAIA,oEAEE,qBAGJ,wDAEE,uCAEF,kEAGA,8CAEA,uDAIF,gEAIE,6BACA,gEAIA,+CACE,0EAIF,sDAEE,+DAGF,sCACA,8BACE,oCAEJ,wBACE,4FAEE,gBAEJ,yGAGI,kBAGJ,CCnHE,2MCFF,oBAGE,wGAKA,iCACE,CADF,wBACE,8GAQA,mBCjBJ,2GAIE,mBACA,6HAMA,YACE,mIAYF,eACA,CAHF,YAGE,4FAGE,8BAKF,uBAkBE,sCACA,CADA,qBAbA,wCAIA,CALF,8BACE,CADF,gBAKE,wCACA,CAOA,kDACA,CACA,kCAKF,6BAGA,4CACE,kDACA,eAGF,cACE,aACA,iBACA,yBACA,8BACA,WAGJ,2BACE,cAGA,+BACA,CAHA,eAGA,wCACA,YACA,iBACA,uEAGA,0BACA,2CAEA,8EAGI,qBACA,CAFF,kBAEE,kBAGN,0CAGE,mCAGA,4BAIA,gEACE,qCACA,8BAEA,gBACA,+CACA,iCAEF,iCAEE,gEACA,qCAGF,8BAEE,+BAIA,yCAEE,qBADA,gBACA,yBAKF,eACA,CAFF,YACE,CACA,iBACA,qDAEA,mDCvIJ,2FAOE,iCACA,CAEA,eACA,CAHA,kBAEA,CAFA,wBAGA,8BACA,eACE,CAFF,YAEE,0BACA,8CAGA,oBACE,oCAGA,kBACE,8DAEA,iBAEN,UACE,8BAIJ,+CAEE,qDAEF,kDAIE,YAEF,CAFE,YAEF,CCpCE,mFADA,kBAKE,CAJF,IAGA,aACE,mCAGA,iDACE,+BAEJ,wBAEE,mBAMA,6CAEF,CAJE,mBAEA,CAEF,kCAGE,CARF,kBACE,CAHA,eAUA,YACA,mBACA,CADA,UACA,wCC9BF,oBDkCE,wBCnCJ,uCACE,+BACA,+DACA,sBAGA,qBCDA,6CAIE,CAPF,uBAGA,CDGE,oBACF,yDAEE,CCDE,2CAGF,CAJA,kCACE,CDJJ,YACE,CAIA,eCTF,CDKE,uBCMA,gCACE,YAEF,oCAEE,wBACA,0BAIF,iBAEA,cADF,UACE,uBAEA,iCAEA,wCAEA,6CAMA,CAYF,gCATI,4BASJ,CAZE,mCAEE,iCAUJ,4BAGE,4DADA,+BACA,CAHF,qBAGE,sCACE,OAEF,iBAHA,SAGA,iHACE,2DAKF,CANA,8EAMA,uSAEE,kBAEF,+FACE,yCCjEJ,WACA,yBAGA,uBACA,gBAEA,uCAIA,CAJA,iCAIA,uCAGA,UACE,gBACA,qBAEA,0CClBJ,gBACE,KAGF,qBACE,YAGF,CAHE,cAGF,gCAEE,mBACA,iEAEA,oCACA,wCAEA,sBACA,WAEA,CAFA,YAEA,8EAEA,mCAFA,iBAEA,6BAIA,wEAKA,sDAIE,CARF,mDAIA,CAIE,cAEF,8CAIA,oBAFE,iBAEF,8CAGE,eAEF,CAFE,YAEF,OAEE,kBAGJ,CAJI,eACA,CAFF,mBAKF,yCCjDE,oBACA,CAFA,iBAEA,uCAKE,iBACA,qCAGA,mBCZJ,CDWI,gBCXJ,6BAEE,eACA,sBAGA,eAEA,sBACA,oDACA,iGAMA,gBAFE,YAEF,8FAME,iJCnBF,YACA,gNAWE,gDAEF,iSAaE,kBACE,gHAKF,oCACE,eACF,CADE,UACF,8CACE,gDACF,wCACE,oBCxCJ,oBAEF,6BACE,QACE,kDAGF,yBACE,kDAmBA,kDAEF,CAhBA,+CAaA,CAbA,oBAaA,0FACE,CADF,gGAfF,cACE,gBACA,CAaA,0BAGA,mQACE,gBAGF,oMACE,iBACA,CAFF,eACE,CADF,gBAEE,aAGJ,iCAEE,CAFF,wCAEE,wBAUE,+VAIE,uEAHA,2BAGA,wXAKJ,iDAGF,CARM,+CACE,iDAIN,CALI,gBAQN,mHACE,gBAGF,2DACE,0EAOA,0EAGF,gBAEE,6DC/EA,kDACA,gCACA,qDAGA,qBACA,qDCFA,cACA,eAEA,yBAGF,sBAEE,iBACA,sNAWA,iBACE,kBACA,wRAgBA,kBAEA,iOAgBA,uCACE,uEAEA,kBAEF,qUAuBE,iDAIJ,CACA,geCxFF,4BAEE,CAQA,6JACA,iDAIA,sEAGA,mDAOF,iDAGE,4DAIA,8CACA,qDAEE,eAFF,cAEE,oBAEF,uBAFE,kCAGA,eACA,iBACA,mBAIA,mDACA,CAHA,uCAEA,CAJA,0CACA,CAIA,gBAJA,gBACA,oBADA,gBAIA,wBAEJ,gBAGE,6BACA,YAHA,iBAGA,gCACA,iEAEA,6CACA,sDACA,0BADA,wBACA,0BACA,oIAIA,mBAFA,YAEA,qBACA,0CAIE,uBAEF,CAHA,yBACE,CAEF,iDACE,mFAKJ,oCACE,CANE,aAKJ,CACE,qEAIA,YAFA,WAEA,CAHA,aACA,CAEA,gBACE,4BACA,sBADA,aACA,gCAMF,oCACA,yDACA,2CAEA,qBAGE,kBAEA,CACA,mCAIF,CARE,YACA,CAOF,iCAEE,CAPA,oBACA,CAQA,oBACE,uDAEJ,sDAGA,CAHA,cAGA,0BACE,oDAIA,oCACA,4BACA,sBAGA,cAEA,oFAGA,sBAEA,yDACE,CAIF,iBAJE,wBAIF,6CAHE,6CAKA,eACA,aACA,CADA,cACA,yCAGJ,kBACE,CAKA,iDAEA,CARF,aACE,4CAGA,kBAIA,wEAGA,wDAGA,kCAOA,iDAGA,CAPF,WAEE,sCAEA,CAJF,2CACE,CAMA,qCACA,+BARF,kBACE,qCAOA,iBAsBA,sBACE,CAvBF,WAKA,CACE,0DAIF,CALA,uDACE,CANF,sBAqBA,4CACA,CALA,gRAIA,YAEE,6CAEN,mCAEE,+CASA,6EAIA,4BChNA,SDmNA,qFCnNA,gDACA,sCAGA,qCACA,sDACA,CAKA,kDAGA,CARA,0CAQA,kBAGA,YACA,sBACA,iBAFA,gBADF,YACE,CAHA,SAKA,kBAEA,SAFA,iBAEA,uEAGA,CAEE,6CAFF,oCAgBI,CAdF,yBACE,qBACF,CAGF,oBACE,CAIF,WACE,CALA,2CAGA,uBACF,CACE,mFAGE,CALF,qBAEA,UAGE,gCAIF,sDAEA,CALE,oCAKF,yCC7CJ,oCACE,CD+CA,yXAQE,sCCrDJ,wCAGA,oCACE","sources":["webpack:///./node_modules/normalize.css/normalize.css","webpack:///./src/furo/assets/styles/base/_print.sass","webpack:///./src/furo/assets/styles/base/_screen-readers.sass","webpack:///./src/furo/assets/styles/base/_theme.sass","webpack:///./src/furo/assets/styles/variables/_fonts.scss","webpack:///./src/furo/assets/styles/variables/_spacing.scss","webpack:///./src/furo/assets/styles/variables/_icons.scss","webpack:///./src/furo/assets/styles/variables/_admonitions.scss","webpack:///./src/furo/assets/styles/variables/_colors.scss","webpack:///./src/furo/assets/styles/base/_typography.sass","webpack:///./src/furo/assets/styles/_scaffold.sass","webpack:///./src/furo/assets/styles/variables/_layout.scss","webpack:///./src/furo/assets/styles/content/_admonitions.sass","webpack:///./src/furo/assets/styles/content/_api.sass","webpack:///./src/furo/assets/styles/content/_blocks.sass","webpack:///./src/furo/assets/styles/content/_captions.sass","webpack:///./src/furo/assets/styles/content/_code.sass","webpack:///./src/furo/assets/styles/content/_footnotes.sass","webpack:///./src/furo/assets/styles/content/_images.sass","webpack:///./src/furo/assets/styles/content/_indexes.sass","webpack:///./src/furo/assets/styles/content/_lists.sass","webpack:///./src/furo/assets/styles/content/_math.sass","webpack:///./src/furo/assets/styles/content/_misc.sass","webpack:///./src/furo/assets/styles/content/_rubrics.sass","webpack:///./src/furo/assets/styles/content/_sidebar.sass","webpack:///./src/furo/assets/styles/content/_tables.sass","webpack:///./src/furo/assets/styles/content/_target.sass","webpack:///./src/furo/assets/styles/content/_gui-labels.sass","webpack:///./src/furo/assets/styles/components/_footer.sass","webpack:///./src/furo/assets/styles/components/_sidebar.sass","webpack:///./src/furo/assets/styles/components/_table_of_contents.sass","webpack:///./src/furo/assets/styles/_shame.sass"],"sourcesContent":["/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */\n\n/* Document\n ========================================================================== */\n\n/**\n * 1. Correct the line height in all browsers.\n * 2. Prevent adjustments of font size after orientation changes in iOS.\n */\n\nhtml {\n line-height: 1.15; /* 1 */\n -webkit-text-size-adjust: 100%; /* 2 */\n}\n\n/* Sections\n ========================================================================== */\n\n/**\n * Remove the margin in all browsers.\n */\n\nbody {\n margin: 0;\n}\n\n/**\n * Render the `main` element consistently in IE.\n */\n\nmain {\n display: block;\n}\n\n/**\n * Correct the font size and margin on `h1` elements within `section` and\n * `article` contexts in Chrome, Firefox, and Safari.\n */\n\nh1 {\n font-size: 2em;\n margin: 0.67em 0;\n}\n\n/* Grouping content\n ========================================================================== */\n\n/**\n * 1. Add the correct box sizing in Firefox.\n * 2. Show the overflow in Edge and IE.\n */\n\nhr {\n box-sizing: content-box; /* 1 */\n height: 0; /* 1 */\n overflow: visible; /* 2 */\n}\n\n/**\n * 1. Correct the inheritance and scaling of font size in all browsers.\n * 2. Correct the odd `em` font sizing in all browsers.\n */\n\npre {\n font-family: monospace, monospace; /* 1 */\n font-size: 1em; /* 2 */\n}\n\n/* Text-level semantics\n ========================================================================== */\n\n/**\n * Remove the gray background on active links in IE 10.\n */\n\na {\n background-color: transparent;\n}\n\n/**\n * 1. Remove the bottom border in Chrome 57-\n * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari.\n */\n\nabbr[title] {\n border-bottom: none; /* 1 */\n text-decoration: underline; /* 2 */\n text-decoration: underline dotted; /* 2 */\n}\n\n/**\n * Add the correct font weight in Chrome, Edge, and Safari.\n */\n\nb,\nstrong {\n font-weight: bolder;\n}\n\n/**\n * 1. Correct the inheritance and scaling of font size in all browsers.\n * 2. Correct the odd `em` font sizing in all browsers.\n */\n\ncode,\nkbd,\nsamp {\n font-family: monospace, monospace; /* 1 */\n font-size: 1em; /* 2 */\n}\n\n/**\n * Add the correct font size in all browsers.\n */\n\nsmall {\n font-size: 80%;\n}\n\n/**\n * Prevent `sub` and `sup` elements from affecting the line height in\n * all browsers.\n */\n\nsub,\nsup {\n font-size: 75%;\n line-height: 0;\n position: relative;\n vertical-align: baseline;\n}\n\nsub {\n bottom: -0.25em;\n}\n\nsup {\n top: -0.5em;\n}\n\n/* Embedded content\n ========================================================================== */\n\n/**\n * Remove the border on images inside links in IE 10.\n */\n\nimg {\n border-style: none;\n}\n\n/* Forms\n ========================================================================== */\n\n/**\n * 1. Change the font styles in all browsers.\n * 2. Remove the margin in Firefox and Safari.\n */\n\nbutton,\ninput,\noptgroup,\nselect,\ntextarea {\n font-family: inherit; /* 1 */\n font-size: 100%; /* 1 */\n line-height: 1.15; /* 1 */\n margin: 0; /* 2 */\n}\n\n/**\n * Show the overflow in IE.\n * 1. Show the overflow in Edge.\n */\n\nbutton,\ninput { /* 1 */\n overflow: visible;\n}\n\n/**\n * Remove the inheritance of text transform in Edge, Firefox, and IE.\n * 1. Remove the inheritance of text transform in Firefox.\n */\n\nbutton,\nselect { /* 1 */\n text-transform: none;\n}\n\n/**\n * Correct the inability to style clickable types in iOS and Safari.\n */\n\nbutton,\n[type=\"button\"],\n[type=\"reset\"],\n[type=\"submit\"] {\n -webkit-appearance: button;\n}\n\n/**\n * Remove the inner border and padding in Firefox.\n */\n\nbutton::-moz-focus-inner,\n[type=\"button\"]::-moz-focus-inner,\n[type=\"reset\"]::-moz-focus-inner,\n[type=\"submit\"]::-moz-focus-inner {\n border-style: none;\n padding: 0;\n}\n\n/**\n * Restore the focus styles unset by the previous rule.\n */\n\nbutton:-moz-focusring,\n[type=\"button\"]:-moz-focusring,\n[type=\"reset\"]:-moz-focusring,\n[type=\"submit\"]:-moz-focusring {\n outline: 1px dotted ButtonText;\n}\n\n/**\n * Correct the padding in Firefox.\n */\n\nfieldset {\n padding: 0.35em 0.75em 0.625em;\n}\n\n/**\n * 1. Correct the text wrapping in Edge and IE.\n * 2. Correct the color inheritance from `fieldset` elements in IE.\n * 3. Remove the padding so developers are not caught out when they zero out\n * `fieldset` elements in all browsers.\n */\n\nlegend {\n box-sizing: border-box; /* 1 */\n color: inherit; /* 2 */\n display: table; /* 1 */\n max-width: 100%; /* 1 */\n padding: 0; /* 3 */\n white-space: normal; /* 1 */\n}\n\n/**\n * Add the correct vertical alignment in Chrome, Firefox, and Opera.\n */\n\nprogress {\n vertical-align: baseline;\n}\n\n/**\n * Remove the default vertical scrollbar in IE 10+.\n */\n\ntextarea {\n overflow: auto;\n}\n\n/**\n * 1. Add the correct box sizing in IE 10.\n * 2. Remove the padding in IE 10.\n */\n\n[type=\"checkbox\"],\n[type=\"radio\"] {\n box-sizing: border-box; /* 1 */\n padding: 0; /* 2 */\n}\n\n/**\n * Correct the cursor style of increment and decrement buttons in Chrome.\n */\n\n[type=\"number\"]::-webkit-inner-spin-button,\n[type=\"number\"]::-webkit-outer-spin-button {\n height: auto;\n}\n\n/**\n * 1. Correct the odd appearance in Chrome and Safari.\n * 2. Correct the outline style in Safari.\n */\n\n[type=\"search\"] {\n -webkit-appearance: textfield; /* 1 */\n outline-offset: -2px; /* 2 */\n}\n\n/**\n * Remove the inner padding in Chrome and Safari on macOS.\n */\n\n[type=\"search\"]::-webkit-search-decoration {\n -webkit-appearance: none;\n}\n\n/**\n * 1. Correct the inability to style clickable types in iOS and Safari.\n * 2. Change font properties to `inherit` in Safari.\n */\n\n::-webkit-file-upload-button {\n -webkit-appearance: button; /* 1 */\n font: inherit; /* 2 */\n}\n\n/* Interactive\n ========================================================================== */\n\n/*\n * Add the correct display in Edge, IE 10+, and Firefox.\n */\n\ndetails {\n display: block;\n}\n\n/*\n * Add the correct display in all browsers.\n */\n\nsummary {\n display: list-item;\n}\n\n/* Misc\n ========================================================================== */\n\n/**\n * Add the correct display in IE 10+.\n */\n\ntemplate {\n display: none;\n}\n\n/**\n * Add the correct display in IE 10.\n */\n\n[hidden] {\n display: none;\n}\n","// This file contains styles for managing print media.\n\n////////////////////////////////////////////////////////////////////////////////\n// Hide elements not relevant to print media.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n // Hide icon container.\n .content-icon-container\n display: none !important\n\n // Hide showing header links if hovering over when printing.\n .headerlink\n display: none !important\n\n // Hide mobile header.\n .mobile-header\n display: none !important\n\n // Hide navigation links.\n .related-pages\n display: none !important\n\n////////////////////////////////////////////////////////////////////////////////\n// Tweaks related to decolorization.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n // Apply a border around code which no longer have a color background.\n .highlight\n border: 0.1pt solid var(--color-foreground-border)\n\n////////////////////////////////////////////////////////////////////////////////\n// Avoid page break in some relevant cases.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n ul, ol, dl, a, table, pre, blockquote, p\n page-break-inside: avoid\n\n h1, h2, h3, h4, h5, h6, img, figure, caption\n page-break-inside: avoid\n page-break-after: avoid\n\n ul, ol, dl\n page-break-before: avoid\n",".visually-hidden\n position: absolute !important\n width: 1px !important\n height: 1px !important\n padding: 0 !important\n margin: -1px !important\n overflow: hidden !important\n clip: rect(0,0,0,0) !important\n white-space: nowrap !important\n border: 0 !important\n color: var(--color-foreground-primary)\n background: var(--color-background-primary)\n\n:-moz-focusring\n outline: auto\n","// This file serves as the \"skeleton\" of the theming logic.\n//\n// This contains the bulk of the logic for handling dark mode, color scheme\n// toggling and the handling of color-scheme-specific hiding of elements.\n\nbody\n @include fonts\n @include spacing\n @include icons\n @include admonitions\n @include default-admonition(#651fff, \"abstract\")\n @include default-topic(#14B8A6, \"pencil\")\n\n @include colors\n\n.only-light\n display: block !important\nhtml body .only-dark\n display: none !important\n\n// Ignore dark-mode hints if print media.\n@media not print\n // Enable dark-mode, if requested.\n body[data-theme=\"dark\"]\n @include colors-dark\n\n html & .only-light\n display: none !important\n .only-dark\n display: block !important\n\n // Enable dark mode, unless explicitly told to avoid.\n @media (prefers-color-scheme: dark)\n body:not([data-theme=\"light\"])\n @include colors-dark\n\n html & .only-light\n display: none !important\n .only-dark\n display: block !important\n\n//\n// Theme toggle presentation\n//\nbody[data-theme=\"auto\"]\n .theme-toggle svg.theme-icon-when-auto-light\n display: block\n\n @media (prefers-color-scheme: dark)\n .theme-toggle svg.theme-icon-when-auto-dark\n display: block\n .theme-toggle svg.theme-icon-when-auto-light\n display: none\n\nbody[data-theme=\"dark\"]\n .theme-toggle svg.theme-icon-when-dark\n display: block\n\nbody[data-theme=\"light\"]\n .theme-toggle svg.theme-icon-when-light\n display: block\n","// Fonts used by this theme.\n//\n// There are basically two things here -- using the system font stack and\n// defining sizes for various elements in %ages. We could have also used `em`\n// but %age is easier to reason about for me.\n\n@mixin fonts {\n // These are adapted from https://systemfontstack.com/\n --font-stack: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial,\n sans-serif, Apple Color Emoji, Segoe UI Emoji;\n --font-stack--monospace: \"SFMono-Regular\", Menlo, Consolas, Monaco,\n Liberation Mono, Lucida Console, monospace;\n --font-stack--headings: var(--font-stack);\n\n --font-size--normal: 100%;\n --font-size--small: 87.5%;\n --font-size--small--2: 81.25%;\n --font-size--small--3: 75%;\n --font-size--small--4: 62.5%;\n\n // Sidebar\n --sidebar-caption-font-size: var(--font-size--small--2);\n --sidebar-item-font-size: var(--font-size--small);\n --sidebar-search-input-font-size: var(--font-size--small);\n\n // Table of Contents\n --toc-font-size: var(--font-size--small--3);\n --toc-font-size--mobile: var(--font-size--normal);\n --toc-title-font-size: var(--font-size--small--4);\n\n // Admonitions\n //\n // These aren't defined in terms of %ages, since nesting these is permitted.\n --admonition-font-size: 0.8125rem;\n --admonition-title-font-size: 0.8125rem;\n\n // Code\n --code-font-size: var(--font-size--small--2);\n\n // API\n --api-font-size: var(--font-size--small);\n}\n","// Spacing for various elements on the page\n//\n// If the user wants to tweak things in a certain way, they are permitted to.\n// They also have to deal with the consequences though!\n\n@mixin spacing {\n // Header!\n --header-height: calc(\n var(--sidebar-item-line-height) + 4 * #{var(--sidebar-item-spacing-vertical)}\n );\n --header-padding: 0.5rem;\n\n // Sidebar\n --sidebar-tree-space-above: 1.5rem;\n --sidebar-caption-space-above: 1rem;\n\n --sidebar-item-line-height: 1rem;\n --sidebar-item-spacing-vertical: 0.5rem;\n --sidebar-item-spacing-horizontal: 1rem;\n --sidebar-item-height: calc(\n var(--sidebar-item-line-height) + 2 *#{var(--sidebar-item-spacing-vertical)}\n );\n\n --sidebar-expander-width: var(--sidebar-item-height); // be square\n\n --sidebar-search-space-above: 0.5rem;\n --sidebar-search-input-spacing-vertical: 0.5rem;\n --sidebar-search-input-spacing-horizontal: 0.5rem;\n --sidebar-search-input-height: 1rem;\n --sidebar-search-icon-size: var(--sidebar-search-input-height);\n\n // Table of Contents\n --toc-title-padding: 0.25rem 0;\n --toc-spacing-vertical: 1.5rem;\n --toc-spacing-horizontal: 1.5rem;\n --toc-item-spacing-vertical: 0.4rem;\n --toc-item-spacing-horizontal: 1rem;\n}\n","// Expose theme icons as CSS variables.\n\n$icons: (\n // Adapted from tabler-icons\n // url: https://tablericons.com/\n \"search\":\n url('data:image/svg+xml;charset=utf-8,'),\n // Factored out from mkdocs-material on 24-Aug-2020.\n // url: https://squidfunk.github.io/mkdocs-material/reference/admonitions/\n \"pencil\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"abstract\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"info\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"flame\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"question\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"warning\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"failure\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"spark\":\n url('data:image/svg+xml;charset=utf-8,')\n);\n\n@mixin icons {\n @each $name, $glyph in $icons {\n --icon-#{$name}: #{$glyph};\n }\n}\n","// Admonitions\n\n// Structure of these is:\n// admonition-class: color \"icon-name\";\n//\n// The colors are translated into CSS variables below. The icons are\n// used directly in the main declarations to set the `mask-image` in\n// the title.\n\n// prettier-ignore\n$admonitions: (\n // Each of these has an reST directives for it.\n \"caution\": #ff9100 \"spark\",\n \"warning\": #ff9100 \"warning\",\n \"danger\": #ff5252 \"spark\",\n \"attention\": #ff5252 \"warning\",\n \"error\": #ff5252 \"failure\",\n \"hint\": #00c852 \"question\",\n \"tip\": #00c852 \"info\",\n \"important\": #00bfa5 \"flame\",\n \"note\": #00b0ff \"pencil\",\n \"seealso\": #448aff \"info\",\n \"admonition-todo\": #808080 \"pencil\"\n);\n\n@mixin default-admonition($color, $icon-name) {\n --color-admonition-title: #{$color};\n --color-admonition-title-background: #{rgba($color, 0.2)};\n\n --icon-admonition-default: var(--icon-#{$icon-name});\n}\n\n@mixin default-topic($color, $icon-name) {\n --color-topic-title: #{$color};\n --color-topic-title-background: #{rgba($color, 0.2)};\n\n --icon-topic-default: var(--icon-#{$icon-name});\n}\n\n@mixin admonitions {\n @each $name, $values in $admonitions {\n --color-admonition-title--#{$name}: #{nth($values, 1)};\n --color-admonition-title-background--#{$name}: #{rgba(\n nth($values, 1),\n 0.2\n )};\n }\n}\n","// Colors used throughout this theme.\n//\n// The aim is to give the user more control. Thus, instead of hard-coding colors\n// in various parts of the stylesheet, the approach taken is to define all\n// colors as CSS variables and reusing them in all the places.\n//\n// `colors-dark` depends on `colors` being included at a lower specificity.\n\n@mixin colors {\n --color-problematic: #b30000;\n\n // Base Colors\n --color-foreground-primary: black; // for main text and headings\n --color-foreground-secondary: #5a5c63; // for secondary text\n --color-foreground-muted: #6b6f76; // for muted text\n --color-foreground-border: #878787; // for content borders\n\n --color-background-primary: white; // for content\n --color-background-secondary: #f8f9fb; // for navigation + ToC\n --color-background-hover: #efeff4ff; // for navigation-item hover\n --color-background-hover--transparent: #efeff400;\n --color-background-border: #eeebee; // for UI borders\n --color-background-item: #ccc; // for \"background\" items (eg: copybutton)\n\n // Announcements\n --color-announcement-background: #000000dd;\n --color-announcement-text: #eeebee;\n\n // Brand colors\n --color-brand-primary: #0a4bff;\n --color-brand-content: #2757dd;\n --color-brand-visited: #872ee0;\n\n // API documentation\n --color-api-background: var(--color-background-hover--transparent);\n --color-api-background-hover: var(--color-background-hover);\n --color-api-overall: var(--color-foreground-secondary);\n --color-api-name: var(--color-problematic);\n --color-api-pre-name: var(--color-problematic);\n --color-api-paren: var(--color-foreground-secondary);\n --color-api-keyword: var(--color-foreground-primary);\n\n --color-api-added: #21632c;\n --color-api-added-border: #38a84d;\n --color-api-changed: #046172;\n --color-api-changed-border: #06a1bc;\n --color-api-deprecated: #605706;\n --color-api-deprecated-border: #f0d90f;\n --color-api-removed: #b30000;\n --color-api-removed-border: #ff5c5c;\n\n --color-highlight-on-target: #ffffcc;\n\n // Inline code background\n --color-inline-code-background: var(--color-background-secondary);\n\n // Highlighted text (search)\n --color-highlighted-background: #ddeeff;\n --color-highlighted-text: var(--color-foreground-primary);\n\n // GUI Labels\n --color-guilabel-background: #ddeeff80;\n --color-guilabel-border: #bedaf580;\n --color-guilabel-text: var(--color-foreground-primary);\n\n // Admonitions!\n --color-admonition-background: transparent;\n\n //////////////////////////////////////////////////////////////////////////////\n // Everything below this should be one of:\n // - var(...)\n // - *-gradient(...)\n // - special literal values (eg: transparent, none)\n //////////////////////////////////////////////////////////////////////////////\n\n // Tables\n --color-table-header-background: var(--color-background-secondary);\n --color-table-border: var(--color-background-border);\n\n // Cards\n --color-card-border: var(--color-background-secondary);\n --color-card-background: transparent;\n --color-card-marginals-background: var(--color-background-secondary);\n\n // Header\n --color-header-background: var(--color-background-primary);\n --color-header-border: var(--color-background-border);\n --color-header-text: var(--color-foreground-primary);\n\n // Sidebar (left)\n --color-sidebar-background: var(--color-background-secondary);\n --color-sidebar-background-border: var(--color-background-border);\n\n --color-sidebar-brand-text: var(--color-foreground-primary);\n --color-sidebar-caption-text: var(--color-foreground-muted);\n --color-sidebar-link-text: var(--color-foreground-secondary);\n --color-sidebar-link-text--top-level: var(--color-brand-primary);\n\n --color-sidebar-item-background: var(--color-sidebar-background);\n --color-sidebar-item-background--current: var(\n --color-sidebar-item-background\n );\n --color-sidebar-item-background--hover: linear-gradient(\n 90deg,\n var(--color-background-hover--transparent) 0%,\n var(--color-background-hover) var(--sidebar-item-spacing-horizontal),\n var(--color-background-hover) 100%\n );\n\n --color-sidebar-item-expander-background: transparent;\n --color-sidebar-item-expander-background--hover: var(\n --color-background-hover\n );\n\n --color-sidebar-search-text: var(--color-foreground-primary);\n --color-sidebar-search-background: var(--color-background-secondary);\n --color-sidebar-search-background--focus: var(--color-background-primary);\n --color-sidebar-search-border: var(--color-background-border);\n --color-sidebar-search-icon: var(--color-foreground-muted);\n\n // Table of Contents (right)\n --color-toc-background: var(--color-background-primary);\n --color-toc-title-text: var(--color-foreground-muted);\n --color-toc-item-text: var(--color-foreground-secondary);\n --color-toc-item-text--hover: var(--color-foreground-primary);\n --color-toc-item-text--active: var(--color-brand-primary);\n\n // Actual page contents\n --color-content-foreground: var(--color-foreground-primary);\n --color-content-background: transparent;\n\n // Links\n --color-link: var(--color-brand-content);\n --color-link-underline: var(--color-background-border);\n --color-link--hover: var(--color-brand-content);\n --color-link-underline--hover: var(--color-foreground-border);\n\n --color-link--visited: var(--color-brand-visited);\n --color-link-underline--visited: var(--color-background-border);\n --color-link--visited--hover: var(--color-brand-visited);\n --color-link-underline--visited--hover: var(--color-foreground-border);\n}\n\n@mixin colors-dark {\n --color-problematic: #ee5151;\n\n // Base Colors\n --color-foreground-primary: #cfd0d0; // for main text and headings\n --color-foreground-secondary: #9ca0a5; // for secondary text\n --color-foreground-muted: #81868d; // for muted text\n --color-foreground-border: #666666; // for content borders\n\n --color-background-primary: #131416; // for content\n --color-background-secondary: #1a1c1e; // for navigation + ToC\n --color-background-hover: #1e2124ff; // for navigation-item hover\n --color-background-hover--transparent: #1e212400;\n --color-background-border: #303335; // for UI borders\n --color-background-item: #444; // for \"background\" items (eg: copybutton)\n\n // Announcements\n --color-announcement-background: #000000dd;\n --color-announcement-text: #eeebee;\n\n // Brand colors\n --color-brand-primary: #3d94ff;\n --color-brand-content: #5ca5ff;\n --color-brand-visited: #b27aeb;\n\n // Highlighted text (search)\n --color-highlighted-background: #083563;\n\n // GUI Labels\n --color-guilabel-background: #08356380;\n --color-guilabel-border: #13395f80;\n\n // API documentation\n --color-api-keyword: var(--color-foreground-secondary);\n --color-highlight-on-target: #333300;\n\n --color-api-added: #3db854;\n --color-api-added-border: #267334;\n --color-api-changed: #09b0ce;\n --color-api-changed-border: #056d80;\n --color-api-deprecated: #b1a10b;\n --color-api-deprecated-border: #6e6407;\n --color-api-removed: #ff7575;\n --color-api-removed-border: #b03b3b;\n\n // Admonitions\n --color-admonition-background: #18181a;\n\n // Cards\n --color-card-border: var(--color-background-secondary);\n --color-card-background: #18181a;\n --color-card-marginals-background: var(--color-background-hover);\n}\n","// This file contains the styling for making the content throughout the page,\n// including fonts, paragraphs, headings and spacing among these elements.\n\nbody\n font-family: var(--font-stack)\npre,\ncode,\nkbd,\nsamp\n font-family: var(--font-stack--monospace)\n\n// Make fonts look slightly nicer.\nbody\n -webkit-font-smoothing: antialiased\n -moz-osx-font-smoothing: grayscale\n\n// Line height from Bootstrap 4.1\narticle\n line-height: 1.5\n\n//\n// Headings\n//\nh1,\nh2,\nh3,\nh4,\nh5,\nh6\n line-height: 1.25\n font-family: var(--font-stack--headings)\n font-weight: bold\n\n border-radius: 0.5rem\n margin-top: 0.5rem\n margin-bottom: 0.5rem\n margin-left: -0.5rem\n margin-right: -0.5rem\n padding-left: 0.5rem\n padding-right: 0.5rem\n\n + p\n margin-top: 0\n\nh1\n font-size: 2.5em\n margin-top: 1.75rem\n margin-bottom: 1rem\nh2\n font-size: 2em\n margin-top: 1.75rem\nh3\n font-size: 1.5em\nh4\n font-size: 1.25em\nh5\n font-size: 1.125em\nh6\n font-size: 1em\n\nsmall\n opacity: 75%\n font-size: 80%\n\n// Paragraph\np\n margin-top: 0.5rem\n margin-bottom: 0.75rem\n\n// Horizontal rules\nhr.docutils\n height: 1px\n padding: 0\n margin: 2rem 0\n background-color: var(--color-background-border)\n border: 0\n\n.centered\n text-align: center\n\n// Links\na\n text-decoration: underline\n\n color: var(--color-link)\n text-decoration-color: var(--color-link-underline)\n\n &:visited\n color: var(--color-link--visited)\n text-decoration-color: var(--color-link-underline--visited)\n &:hover\n color: var(--color-link--visited--hover)\n text-decoration-color: var(--color-link-underline--visited--hover)\n\n &:hover\n color: var(--color-link--hover)\n text-decoration-color: var(--color-link-underline--hover)\n &.muted-link\n color: inherit\n &:hover\n color: var(--color-link--hover)\n text-decoration-color: var(--color-link-underline--hover)\n &:visited\n color: var(--color-link--visited--hover)\n text-decoration-color: var(--color-link-underline--visited--hover)\n","// This file contains the styles for the overall layouting of the documentation\n// skeleton, including the responsive changes as well as sidebar toggles.\n//\n// This is implemented as a mobile-last design, which isn't ideal, but it is\n// reasonably good-enough and I got pretty tired by the time I'd finished this\n// to move the rules around to fix this. Shouldn't take more than 3-4 hours,\n// if you know what you're doing tho.\n\n// HACK: Not all browsers account for the scrollbar width in media queries.\n// This results in horizontal scrollbars in the breakpoint where we go\n// from displaying everything to hiding the ToC. We accomodate for this by\n// adding a bit of padding to the TOC drawer, disabling the horizontal\n// scrollbar and allowing the scrollbars to cover the padding.\n// https://www.456bereastreet.com/archive/201301/media_query_width_and_vertical_scrollbars/\n\n// HACK: Always having the scrollbar visible, prevents certain browsers from\n// causing the content to stutter horizontally between taller-than-viewport and\n// not-taller-than-viewport pages.\n\nhtml\n overflow-x: hidden\n overflow-y: scroll\n scroll-behavior: smooth\n\n.sidebar-scroll, .toc-scroll, article[role=main] *\n // Override Firefox scrollbar style\n scrollbar-width: thin\n scrollbar-color: var(--color-foreground-border) transparent\n\n // Override Chrome scrollbar styles\n &::-webkit-scrollbar\n width: 0.25rem\n height: 0.25rem\n &::-webkit-scrollbar-thumb\n background-color: var(--color-foreground-border)\n border-radius: 0.125rem\n\n//\n// Overalls\n//\nhtml,\nbody\n height: 100%\n color: var(--color-foreground-primary)\n background: var(--color-background-primary)\n\n.skip-to-content\n position: fixed\n padding: 1rem\n border-radius: 1rem\n left: 0.25rem\n top: 0.25rem\n z-index: 40\n background: var(--color-background-primary)\n color: var(--color-foreground-primary)\n\n transform: translateY(-200%)\n transition: transform 300ms ease-in-out\n\n &:focus-within\n transform: translateY(0%)\n\narticle\n color: var(--color-content-foreground)\n background: var(--color-content-background)\n overflow-wrap: break-word\n\n.page\n display: flex\n // fill the viewport for pages with little content.\n min-height: 100%\n\n.mobile-header\n width: 100%\n height: var(--header-height)\n background-color: var(--color-header-background)\n color: var(--color-header-text)\n border-bottom: 1px solid var(--color-header-border)\n\n // Looks like sub-script/super-script have this, and we need this to\n // be \"on top\" of those.\n z-index: 10\n\n // We don't show the header on large screens.\n display: none\n\n // Add shadow when scrolled\n &.scrolled\n border-bottom: none\n box-shadow: 0 0 0.2rem rgba(0, 0, 0, 0.1), 0 0.2rem 0.4rem rgba(0, 0, 0, 0.2)\n\n .header-center\n a\n color: var(--color-header-text)\n text-decoration: none\n\n.main\n display: flex\n flex: 1\n\n// Sidebar (left) also covers the entire left portion of screen.\n.sidebar-drawer\n box-sizing: border-box\n\n border-right: 1px solid var(--color-sidebar-background-border)\n background: var(--color-sidebar-background)\n\n display: flex\n justify-content: flex-end\n // These next two lines took me two days to figure out.\n width: calc((100% - #{$full-width}) / 2 + #{$sidebar-width})\n min-width: $sidebar-width\n\n// Scroll-along sidebars\n.sidebar-container,\n.toc-drawer\n box-sizing: border-box\n width: $sidebar-width\n\n.toc-drawer\n background: var(--color-toc-background)\n // See HACK described on top of this document\n padding-right: 1rem\n\n.sidebar-sticky,\n.toc-sticky\n position: sticky\n top: 0\n height: min(100%, 100vh)\n height: 100vh\n\n display: flex\n flex-direction: column\n\n.sidebar-scroll,\n.toc-scroll\n flex-grow: 1\n flex-shrink: 1\n\n overflow: auto\n scroll-behavior: smooth\n\n// Central items.\n.content\n padding: 0 $content-padding\n width: $content-width\n\n display: flex\n flex-direction: column\n justify-content: space-between\n\n.icon\n display: inline-block\n height: 1rem\n width: 1rem\n svg\n width: 100%\n height: 100%\n\n//\n// Accommodate announcement banner\n//\n.announcement\n background-color: var(--color-announcement-background)\n color: var(--color-announcement-text)\n\n height: var(--header-height)\n display: flex\n align-items: center\n overflow-x: auto\n & + .page\n min-height: calc(100% - var(--header-height))\n\n.announcement-content\n box-sizing: border-box\n padding: 0.5rem\n min-width: 100%\n white-space: nowrap\n text-align: center\n\n a\n color: var(--color-announcement-text)\n text-decoration-color: var(--color-announcement-text)\n\n &:hover\n color: var(--color-announcement-text)\n text-decoration-color: var(--color-link--hover)\n\n////////////////////////////////////////////////////////////////////////////////\n// Toggles for theme\n////////////////////////////////////////////////////////////////////////////////\n.no-js .theme-toggle-container // don't show theme toggle if there's no JS\n display: none\n\n.theme-toggle-container\n display: flex\n\n.theme-toggle\n display: flex\n cursor: pointer\n border: none\n padding: 0\n background: transparent\n\n.theme-toggle svg\n height: 1.25rem\n width: 1.25rem\n color: var(--color-foreground-primary)\n display: none\n\n.theme-toggle-header\n display: flex\n align-items: center\n justify-content: center\n\n////////////////////////////////////////////////////////////////////////////////\n// Toggles for elements\n////////////////////////////////////////////////////////////////////////////////\n.toc-overlay-icon, .nav-overlay-icon\n display: none\n cursor: pointer\n\n .icon\n color: var(--color-foreground-secondary)\n height: 1.5rem\n width: 1.5rem\n\n.toc-header-icon, .nav-overlay-icon\n // for when we set display: flex\n justify-content: center\n align-items: center\n\n.toc-content-icon\n height: 1.5rem\n width: 1.5rem\n\n.content-icon-container\n float: right\n display: flex\n margin-top: 1.5rem\n margin-left: 1rem\n margin-bottom: 1rem\n gap: 0.5rem\n\n .edit-this-page, .view-this-page\n svg\n color: inherit\n height: 1.25rem\n width: 1.25rem\n\n.sidebar-toggle\n position: absolute\n display: none\n// \n.sidebar-toggle[name=\"__toc\"]\n left: 20px\n.sidebar-toggle:checked\n left: 40px\n// \n\n.overlay\n position: fixed\n top: 0\n width: 0\n height: 0\n\n transition: width 0ms, height 0ms, opacity 250ms ease-out\n\n opacity: 0\n background-color: rgba(0, 0, 0, 0.54)\n.sidebar-overlay\n z-index: 20\n.toc-overlay\n z-index: 40\n\n// Keep things on top and smooth.\n.sidebar-drawer\n z-index: 30\n transition: left 250ms ease-in-out\n.toc-drawer\n z-index: 50\n transition: right 250ms ease-in-out\n\n// Show the Sidebar\n#__navigation:checked\n & ~ .sidebar-overlay\n width: 100%\n height: 100%\n opacity: 1\n & ~ .page\n .sidebar-drawer\n top: 0\n left: 0\n // Show the toc sidebar\n#__toc:checked\n & ~ .toc-overlay\n width: 100%\n height: 100%\n opacity: 1\n & ~ .page\n .toc-drawer\n top: 0\n right: 0\n\n////////////////////////////////////////////////////////////////////////////////\n// Back to top\n////////////////////////////////////////////////////////////////////////////////\n.back-to-top\n text-decoration: none\n\n display: none\n position: fixed\n left: 0\n top: 1rem\n padding: 0.5rem\n padding-right: 0.75rem\n border-radius: 1rem\n font-size: 0.8125rem\n\n background: var(--color-background-primary)\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), #6b728080 0px 0px 1px 0px\n\n z-index: 10\n\n margin-left: 50%\n transform: translateX(-50%)\n svg\n height: 1rem\n width: 1rem\n fill: currentColor\n display: inline-block\n\n span\n margin-left: 0.25rem\n\n .show-back-to-top &\n display: flex\n align-items: center\n\n////////////////////////////////////////////////////////////////////////////////\n// Responsive layouting\n////////////////////////////////////////////////////////////////////////////////\n// Make things a bit bigger on bigger screens.\n@media (min-width: $full-width + $sidebar-width)\n html\n font-size: 110%\n\n@media (max-width: $full-width)\n // Collapse \"toc\" into the icon.\n .toc-content-icon\n display: flex\n .toc-drawer\n position: fixed\n height: 100vh\n top: 0\n right: -$sidebar-width\n border-left: 1px solid var(--color-background-muted)\n .toc-tree\n border-left: none\n font-size: var(--toc-font-size--mobile)\n\n // Accomodate for a changed content width.\n .sidebar-drawer\n width: calc((100% - #{$full-width - $sidebar-width}) / 2 + #{$sidebar-width})\n\n@media (max-width: $content-padded-width + $sidebar-width)\n // Center the page\n .content\n margin-left: auto\n margin-right: auto\n padding: 0 $content-padding--small\n\n@media (max-width: $content-padded-width--small + $sidebar-width)\n // Collapse \"navigation\".\n .nav-overlay-icon\n display: flex\n .sidebar-drawer\n position: fixed\n height: 100vh\n width: $sidebar-width\n\n top: 0\n left: -$sidebar-width\n\n // Swap which icon is visible.\n .toc-header-icon, .theme-toggle-header\n display: flex\n .toc-content-icon, .theme-toggle-content\n display: none\n\n // Show the header.\n .mobile-header\n position: sticky\n top: 0\n display: flex\n justify-content: space-between\n align-items: center\n\n .header-left,\n .header-right\n display: flex\n height: var(--header-height)\n padding: 0 var(--header-padding)\n label\n height: 100%\n width: 100%\n user-select: none\n\n .nav-overlay-icon .icon,\n .theme-toggle svg\n height: 1.5rem\n width: 1.5rem\n\n // Add a scroll margin for the content\n :target\n scroll-margin-top: calc(var(--header-height) + 2.5rem)\n\n // Show back-to-top below the header\n .back-to-top\n top: calc(var(--header-height) + 0.5rem)\n\n // Accommodate for the header.\n .page\n flex-direction: column\n justify-content: center\n\n@media (max-width: $content-width + 2* $content-padding--small)\n // Content should respect window limits.\n .content\n width: 100%\n overflow-x: auto\n\n@media (max-width: $content-width)\n article[role=main] aside.sidebar\n float: none\n width: 100%\n margin: 1rem 0\n","// Overall Layout Variables\n//\n// Because CSS variables can't be used in media queries. The fact that this\n// makes the layout non-user-configurable is a good thing.\n$content-padding: 3em;\n$content-padding--small: 1em;\n$content-width: 46em;\n$sidebar-width: 15em;\n$content-padded-width: $content-width + 2 * $content-padding;\n$content-padded-width--small: $content-width + 2 * $content-padding--small;\n$full-width: $content-padded-width + 2 * $sidebar-width;\n","//\n// The design here is strongly inspired by mkdocs-material.\n.admonition, .topic\n margin: 1rem auto\n padding: 0 0.5rem 0.5rem 0.5rem\n\n background: var(--color-admonition-background)\n\n border-radius: 0.2rem\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n font-size: var(--admonition-font-size)\n\n overflow: hidden\n page-break-inside: avoid\n\n // First element should have no margin, since the title has it.\n > :nth-child(2)\n margin-top: 0\n\n // Last item should have no margin, since we'll control that w/ padding\n > :last-child\n margin-bottom: 0\n\n.admonition p.admonition-title,\np.topic-title\n position: relative\n margin: 0 -0.5rem 0.5rem\n padding-left: 2rem\n padding-right: .5rem\n padding-top: .4rem\n padding-bottom: .4rem\n\n font-weight: 500\n font-size: var(--admonition-title-font-size)\n line-height: 1.3\n\n // Our fancy icon\n &::before\n content: \"\"\n position: absolute\n left: 0.5rem\n width: 1rem\n height: 1rem\n\n// Default styles\np.admonition-title\n background-color: var(--color-admonition-title-background)\n &::before\n background-color: var(--color-admonition-title)\n mask-image: var(--icon-admonition-default)\n mask-repeat: no-repeat\n\np.topic-title\n background-color: var(--color-topic-title-background)\n &::before\n background-color: var(--color-topic-title)\n mask-image: var(--icon-topic-default)\n mask-repeat: no-repeat\n\n//\n// Variants\n//\n.admonition\n border-left: 0.2rem solid var(--color-admonition-title)\n\n @each $type, $value in $admonitions\n &.#{$type}\n border-left-color: var(--color-admonition-title--#{$type})\n > .admonition-title\n background-color: var(--color-admonition-title-background--#{$type})\n &::before\n background-color: var(--color-admonition-title--#{$type})\n mask-image: var(--icon-#{nth($value, 2)})\n\n.admonition-todo > .admonition-title\n text-transform: uppercase\n","// This file stylizes the API documentation (stuff generated by autodoc). It's\n// deeply nested due to how autodoc structures the HTML without enough classes\n// to select the relevant items.\n\n// API docs!\ndl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)\n // Tweak the spacing of all the things!\n dd\n margin-left: 2rem\n > :first-child\n margin-top: 0.125rem\n > :last-child\n margin-bottom: 0.75rem\n\n // This is used for the arguments\n .field-list\n margin-bottom: 0.75rem\n\n // \"Headings\" (like \"Parameters\" and \"Return\")\n > dt\n text-transform: uppercase\n font-size: var(--font-size--small)\n\n dd:empty\n margin-bottom: 0.5rem\n dd > ul\n margin-left: -1.2rem\n > li\n > p:nth-child(2)\n margin-top: 0\n // When the last-empty-paragraph follows a paragraph, it doesn't need\n // to augument the existing spacing.\n > p + p:last-child:empty\n margin-top: 0\n margin-bottom: 0\n\n // Colorize the elements\n > dt\n color: var(--color-api-overall)\n\n.sig:not(.sig-inline)\n font-weight: bold\n\n font-size: var(--api-font-size)\n font-family: var(--font-stack--monospace)\n\n margin-left: -0.25rem\n margin-right: -0.25rem\n padding-top: 0.25rem\n padding-bottom: 0.25rem\n padding-right: 0.5rem\n\n // These are intentionally em, to properly match the font size.\n padding-left: 3em\n text-indent: -2.5em\n\n border-radius: 0.25rem\n\n background: var(--color-api-background)\n transition: background 100ms ease-out\n\n &:hover\n background: var(--color-api-background-hover)\n\n // adjust the size of the [source] link on the right.\n a.reference\n .viewcode-link\n font-weight: normal\n width: 4.25rem\n\nem.property\n font-style: normal\n &:first-child\n color: var(--color-api-keyword)\n.sig-name\n color: var(--color-api-name)\n.sig-prename\n font-weight: normal\n color: var(--color-api-pre-name)\n.sig-paren\n color: var(--color-api-paren)\n.sig-param\n font-style: normal\n\ndiv.versionadded,\ndiv.versionchanged,\ndiv.deprecated,\ndiv.versionremoved\n border-left: 0.1875rem solid\n border-radius: 0.125rem\n\n padding-left: 0.75rem\n\n p\n margin-top: 0.125rem\n margin-bottom: 0.125rem\n\ndiv.versionadded\n border-color: var(--color-api-added-border)\n .versionmodified\n color: var(--color-api-added)\n\ndiv.versionchanged\n border-color: var(--color-api-changed-border)\n .versionmodified\n color: var(--color-api-changed)\n\ndiv.deprecated\n border-color: var(--color-api-deprecated-border)\n .versionmodified\n color: var(--color-api-deprecated)\n\ndiv.versionremoved\n border-color: var(--color-api-removed-border)\n .versionmodified\n color: var(--color-api-removed)\n\n// Align the [docs] and [source] to the right.\n.viewcode-link, .viewcode-back\n float: right\n text-align: right\n",".line-block\n margin-top: 0.5rem\n margin-bottom: 0.75rem\n .line-block\n margin-top: 0rem\n margin-bottom: 0rem\n padding-left: 1rem\n","// Captions\narticle p.caption,\ntable > caption,\n.code-block-caption\n font-size: var(--font-size--small)\n text-align: center\n\n// Caption above a TOCTree\n.toctree-wrapper.compound\n .caption, :not(.caption) > .caption-text\n font-size: var(--font-size--small)\n text-transform: uppercase\n\n text-align: initial\n margin-bottom: 0\n\n > ul\n margin-top: 0\n margin-bottom: 0\n","// Inline code\ncode.literal, .sig-inline\n background: var(--color-inline-code-background)\n border-radius: 0.2em\n // Make the font smaller, and use padding to recover.\n font-size: var(--font-size--small--2)\n padding: 0.1em 0.2em\n\n pre.literal-block &\n font-size: inherit\n padding: 0\n\n p &\n border: 1px solid var(--color-background-border)\n\n.sig-inline\n font-family: var(--font-stack--monospace)\n\n// Code and Literal Blocks\n$code-spacing-vertical: 0.625rem\n$code-spacing-horizontal: 0.875rem\n\n// Wraps every literal block + line numbers.\ndiv[class*=\" highlight-\"],\ndiv[class^=\"highlight-\"]\n margin: 1em 0\n display: flex\n\n .table-wrapper\n margin: 0\n padding: 0\n\npre\n margin: 0\n padding: 0\n overflow: auto\n\n // Needed to have more specificity than pygments' \"pre\" selector. :(\n article[role=\"main\"] .highlight &\n line-height: 1.5\n\n &.literal-block,\n .highlight &\n font-size: var(--code-font-size)\n padding: $code-spacing-vertical $code-spacing-horizontal\n\n // Make it look like all the other blocks.\n &.literal-block\n margin-top: 1rem\n margin-bottom: 1rem\n\n border-radius: 0.2rem\n background-color: var(--color-code-background)\n color: var(--color-code-foreground)\n\n// All code is always contained in this.\n.highlight\n width: 100%\n border-radius: 0.2rem\n\n // Make line numbers and prompts un-selectable.\n .gp, span.linenos\n user-select: none\n pointer-events: none\n\n // Expand the line-highlighting.\n .hll\n display: block\n margin-left: -$code-spacing-horizontal\n margin-right: -$code-spacing-horizontal\n padding-left: $code-spacing-horizontal\n padding-right: $code-spacing-horizontal\n\n/* Make code block captions be nicely integrated */\n.code-block-caption\n display: flex\n padding: $code-spacing-vertical $code-spacing-horizontal\n\n border-radius: 0.25rem\n border-bottom-left-radius: 0\n border-bottom-right-radius: 0\n font-weight: 300\n border-bottom: 1px solid\n\n background-color: var(--color-code-background)\n color: var(--color-code-foreground)\n border-color: var(--color-background-border)\n\n + div[class]\n margin-top: 0\n pre\n border-top-left-radius: 0\n border-top-right-radius: 0\n\n// When `html_codeblock_linenos_style` is table.\n.highlighttable\n width: 100%\n display: block\n tbody\n display: block\n\n tr\n display: flex\n\n // Line numbers\n td.linenos\n background-color: var(--color-code-background)\n color: var(--color-code-foreground)\n padding: $code-spacing-vertical $code-spacing-horizontal\n padding-right: 0\n border-top-left-radius: 0.2rem\n border-bottom-left-radius: 0.2rem\n\n .linenodiv\n padding-right: $code-spacing-horizontal\n font-size: var(--code-font-size)\n box-shadow: -0.0625rem 0 var(--color-foreground-border) inset\n\n // Actual code\n td.code\n padding: 0\n display: block\n flex: 1\n overflow: hidden\n\n .highlight\n border-top-left-radius: 0\n border-bottom-left-radius: 0\n\n// When `html_codeblock_linenos_style` is inline.\n.highlight\n span.linenos\n display: inline-block\n padding-left: 0\n padding-right: $code-spacing-horizontal\n margin-right: $code-spacing-horizontal\n box-shadow: -0.0625rem 0 var(--color-foreground-border) inset\n","// Inline Footnote Reference\n.footnote-reference\n font-size: var(--font-size--small--4)\n vertical-align: super\n\n// Definition list, listing the content of each note.\n// docutils <= 0.17\ndl.footnote.brackets\n font-size: var(--font-size--small)\n color: var(--color-foreground-secondary)\n\n display: grid\n grid-template-columns: max-content auto\n dt\n margin: 0\n > .fn-backref\n margin-left: 0.25rem\n\n &:after\n content: \":\"\n\n .brackets\n &:before\n content: \"[\"\n &:after\n content: \"]\"\n\n dd\n margin: 0\n padding: 0 1rem\n\n// docutils >= 0.18\naside.footnote\n font-size: var(--font-size--small)\n color: var(--color-foreground-secondary)\n\naside.footnote > span,\ndiv.citation > span\n float: left\n font-weight: 500\n padding-right: 0.25rem\n\naside.footnote > *:not(span),\ndiv.citation > p\n margin-left: 2rem\n","//\n// Figures\n//\nimg\n box-sizing: border-box\n max-width: 100%\n height: auto\n\narticle\n figure, .figure\n border-radius: 0.2rem\n\n margin: 0\n :last-child\n margin-bottom: 0\n\n .align-left\n float: left\n clear: left\n margin: 0 1rem 1rem\n\n .align-right\n float: right\n clear: right\n margin: 0 1rem 1rem\n\n .align-default,\n .align-center\n display: block\n text-align: center\n margin-left: auto\n margin-right: auto\n\n // WELL, table needs to be stylised like a table.\n table.align-default\n display: table\n text-align: initial\n",".genindex-jumpbox, .domainindex-jumpbox\n border-top: 1px solid var(--color-background-border)\n border-bottom: 1px solid var(--color-background-border)\n padding: 0.25rem\n\n.genindex-section, .domainindex-section\n h2\n margin-top: 0.75rem\n margin-bottom: 0.5rem\n ul\n margin-top: 0\n margin-bottom: 0\n","ul,\nol\n padding-left: 1.2rem\n\n // Space lists out like paragraphs\n margin-top: 1rem\n margin-bottom: 1rem\n // reduce margins within li.\n li\n > p:first-child\n margin-top: 0.25rem\n margin-bottom: 0.25rem\n\n > p:last-child\n margin-top: 0.25rem\n\n > ul,\n > ol\n margin-top: 0.5rem\n margin-bottom: 0.5rem\n\nol\n &.arabic\n list-style: decimal\n &.loweralpha\n list-style: lower-alpha\n &.upperalpha\n list-style: upper-alpha\n &.lowerroman\n list-style: lower-roman\n &.upperroman\n list-style: upper-roman\n\n// Don't space lists out when they're \"simple\" or in a `.. toctree::`\n.simple,\n.toctree-wrapper\n li\n > ul,\n > ol\n margin-top: 0\n margin-bottom: 0\n\n// Definition Lists\n.field-list,\n.option-list,\ndl:not([class]),\ndl.simple,\ndl.footnote,\ndl.glossary\n dt\n font-weight: 500\n margin-top: 0.25rem\n + dt\n margin-top: 0\n\n .classifier::before\n content: \":\"\n margin-left: 0.2rem\n margin-right: 0.2rem\n\n dd\n > p:first-child,\n ul\n margin-top: 0.125rem\n\n ul\n margin-bottom: 0.125rem\n",".math-wrapper\n width: 100%\n overflow-x: auto\n\ndiv.math\n position: relative\n text-align: center\n\n .headerlink,\n &:focus .headerlink\n display: none\n\n &:hover .headerlink\n display: inline-block\n\n span.eqno\n position: absolute\n right: 0.5rem\n top: 50%\n transform: translate(0, -50%)\n z-index: 1\n","// Abbreviations\nabbr[title]\n cursor: help\n\n// \"Problematic\" content, as identified by Sphinx\n.problematic\n color: var(--color-problematic)\n\n// Keyboard / Mouse \"instructions\"\nkbd:not(.compound)\n margin: 0 0.2rem\n padding: 0 0.2rem\n border-radius: 0.2rem\n border: 1px solid var(--color-foreground-border)\n color: var(--color-foreground-primary)\n vertical-align: text-bottom\n\n font-size: var(--font-size--small--3)\n display: inline-block\n\n box-shadow: 0 0.0625rem 0 rgba(0, 0, 0, 0.2), inset 0 0 0 0.125rem var(--color-background-primary)\n\n background-color: var(--color-background-secondary)\n\n// Blockquote\nblockquote\n border-left: 4px solid var(--color-background-border)\n background: var(--color-background-secondary)\n\n margin-left: 0\n margin-right: 0\n padding: 0.5rem 1rem\n\n .attribution\n font-weight: 600\n text-align: right\n\n &.pull-quote,\n &.highlights\n font-size: 1.25em\n\n &.epigraph,\n &.pull-quote\n border-left-width: 0\n border-radius: 0.5rem\n\n &.highlights\n border-left-width: 0\n background: transparent\n\n// Center align embedded-in-text images\np .reference img\n vertical-align: middle\n","p.rubric\n line-height: 1.25\n font-weight: bold\n font-size: 1.125em\n\n // For Numpy-style documentation that's got rubrics within it.\n // https://github.com/pradyunsg/furo/discussions/505\n dd &\n line-height: inherit\n font-weight: inherit\n\n font-size: var(--font-size--small)\n text-transform: uppercase\n","article .sidebar\n float: right\n clear: right\n width: 30%\n\n margin-left: 1rem\n margin-right: 0\n\n border-radius: 0.2rem\n background-color: var(--color-background-secondary)\n border: var(--color-background-border) 1px solid\n\n > *\n padding-left: 1rem\n padding-right: 1rem\n\n > ul, > ol // lists need additional padding, because bullets.\n padding-left: 2.2rem\n\n .sidebar-title\n margin: 0\n padding: 0.5rem 1rem\n border-bottom: var(--color-background-border) 1px solid\n\n font-weight: 500\n\n// TODO: subtitle\n// TODO: dedicated variables?\n","[role=main] .table-wrapper.container\n width: 100%\n overflow-x: auto\n margin-top: 1rem\n margin-bottom: 0.5rem\n padding: 0.2rem 0.2rem 0.75rem\n\ntable.docutils\n border-radius: 0.2rem\n border-spacing: 0\n border-collapse: collapse\n\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n th\n background: var(--color-table-header-background)\n\n td,\n th\n // Space things out properly\n padding: 0 0.25rem\n\n // Get the borders looking just-right.\n border-left: 1px solid var(--color-table-border)\n border-right: 1px solid var(--color-table-border)\n border-bottom: 1px solid var(--color-table-border)\n\n p\n margin: 0.25rem\n\n &:first-child\n border-left: none\n &:last-child\n border-right: none\n\n // MyST-parser tables set these classes for control of column alignment\n &.text-left\n text-align: left\n &.text-right\n text-align: right\n &.text-center\n text-align: center\n",":target\n scroll-margin-top: 2.5rem\n\n@media (max-width: $full-width - $sidebar-width)\n :target\n scroll-margin-top: calc(2.5rem + var(--header-height))\n\n // When a heading is selected\n section > span:target\n scroll-margin-top: calc(2.8rem + var(--header-height))\n\n// Permalinks\n.headerlink\n font-weight: 100\n user-select: none\n\nh1,\nh2,\nh3,\nh4,\nh5,\nh6,\ndl dt,\np.caption,\nfigcaption p,\ntable > caption,\n.code-block-caption\n > .headerlink\n margin-left: 0.5rem\n visibility: hidden\n &:hover > .headerlink\n visibility: visible\n\n // Don't change to link-like, if someone adds the contents directive.\n > .toc-backref\n color: inherit\n text-decoration-line: none\n\n// Figure and table captions are special.\nfigure:hover > figcaption > p > .headerlink,\ntable:hover > caption > .headerlink\n visibility: visible\n\n:target >, // Regular section[id] style anchors\nspan:target ~ // Non-regular span[id] style \"extra\" anchors\n h1,\n h2,\n h3,\n h4,\n h5,\n h6\n &:nth-of-type(1)\n background-color: var(--color-highlight-on-target)\n // .headerlink\n // visibility: visible\n code.literal\n background-color: transparent\n\ntable:target > caption,\nfigure:target\n background-color: var(--color-highlight-on-target)\n\n// Inline page contents\n.this-will-duplicate-information-and-it-is-still-useful-here li :target\n background-color: var(--color-highlight-on-target)\n\n// Code block permalinks\n.literal-block-wrapper:target .code-block-caption\n background-color: var(--color-highlight-on-target)\n\n// When a definition list item is selected\n//\n// There isn't really an alternative to !important here, due to the\n// high-specificity of API documentation's selector.\ndt:target\n background-color: var(--color-highlight-on-target) !important\n\n// When a footnote reference is selected\n.footnote > dt:target + dd,\n.footnote-reference:target\n background-color: var(--color-highlight-on-target)\n",".guilabel\n background-color: var(--color-guilabel-background)\n border: 1px solid var(--color-guilabel-border)\n color: var(--color-guilabel-text)\n\n padding: 0 0.3em\n border-radius: 0.5em\n font-size: 0.9em\n","// This file contains the styles used for stylizing the footer that's shown\n// below the content.\n\nfooter\n font-size: var(--font-size--small)\n display: flex\n flex-direction: column\n\n margin-top: 2rem\n\n// Bottom of page information\n.bottom-of-page\n display: flex\n align-items: center\n justify-content: space-between\n\n margin-top: 1rem\n padding-top: 1rem\n padding-bottom: 1rem\n\n color: var(--color-foreground-secondary)\n border-top: 1px solid var(--color-background-border)\n\n line-height: 1.5\n\n @media (max-width: $content-width)\n text-align: center\n flex-direction: column-reverse\n gap: 0.25rem\n\n .left-details\n font-size: var(--font-size--small)\n\n .right-details\n display: flex\n flex-direction: column\n gap: 0.25rem\n text-align: right\n\n .icons\n display: flex\n justify-content: flex-end\n gap: 0.25rem\n font-size: 1rem\n\n a\n text-decoration: none\n\n svg,\n img\n font-size: 1.125rem\n height: 1em\n width: 1em\n\n// Next/Prev page information\n.related-pages\n a\n display: flex\n align-items: center\n\n text-decoration: none\n &:hover .page-info .title\n text-decoration: underline\n color: var(--color-link)\n text-decoration-color: var(--color-link-underline)\n\n svg.furo-related-icon,\n svg.furo-related-icon > use\n flex-shrink: 0\n\n color: var(--color-foreground-border)\n\n width: 0.75rem\n height: 0.75rem\n margin: 0 0.5rem\n\n &.next-page\n max-width: 50%\n\n float: right\n clear: right\n text-align: right\n\n &.prev-page\n max-width: 50%\n\n float: left\n clear: left\n\n svg\n transform: rotate(180deg)\n\n.page-info\n display: flex\n flex-direction: column\n overflow-wrap: anywhere\n\n .next-page &\n align-items: flex-end\n\n .context\n display: flex\n align-items: center\n\n padding-bottom: 0.1rem\n\n color: var(--color-foreground-muted)\n font-size: var(--font-size--small)\n text-decoration: none\n","// This file contains the styles for the contents of the left sidebar, which\n// contains the navigation tree, logo, search etc.\n\n////////////////////////////////////////////////////////////////////////////////\n// Brand on top of the scrollable tree.\n////////////////////////////////////////////////////////////////////////////////\n.sidebar-brand\n display: flex\n flex-direction: column\n flex-shrink: 0\n\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n text-decoration: none\n\n.sidebar-brand-text\n color: var(--color-sidebar-brand-text)\n overflow-wrap: break-word\n margin: var(--sidebar-item-spacing-vertical) 0\n font-size: 1.5rem\n\n.sidebar-logo-container\n margin: var(--sidebar-item-spacing-vertical) 0\n\n.sidebar-logo\n margin: 0 auto\n display: block\n max-width: 100%\n\n////////////////////////////////////////////////////////////////////////////////\n// Search\n////////////////////////////////////////////////////////////////////////////////\n.sidebar-search-container\n display: flex\n align-items: center\n margin-top: var(--sidebar-search-space-above)\n\n position: relative\n\n background: var(--color-sidebar-search-background)\n &:hover,\n &:focus-within\n background: var(--color-sidebar-search-background--focus)\n\n &::before\n content: \"\"\n position: absolute\n left: var(--sidebar-item-spacing-horizontal)\n width: var(--sidebar-search-icon-size)\n height: var(--sidebar-search-icon-size)\n\n background-color: var(--color-sidebar-search-icon)\n mask-image: var(--icon-search)\n\n.sidebar-search\n box-sizing: border-box\n\n border: none\n border-top: 1px solid var(--color-sidebar-search-border)\n border-bottom: 1px solid var(--color-sidebar-search-border)\n\n padding-top: var(--sidebar-search-input-spacing-vertical)\n padding-bottom: var(--sidebar-search-input-spacing-vertical)\n padding-right: var(--sidebar-search-input-spacing-horizontal)\n padding-left: calc(var(--sidebar-item-spacing-horizontal) + var(--sidebar-search-input-spacing-horizontal) + var(--sidebar-search-icon-size))\n\n width: 100%\n\n color: var(--color-sidebar-search-foreground)\n background: transparent\n z-index: 10\n\n &:focus\n outline: none\n\n &::placeholder\n font-size: var(--sidebar-search-input-font-size)\n\n//\n// Hide Search Matches link\n//\n#searchbox .highlight-link\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0\n margin: 0\n text-align: center\n\n a\n color: var(--color-sidebar-search-icon)\n font-size: var(--font-size--small--2)\n\n////////////////////////////////////////////////////////////////////////////////\n// Structure/Skeleton of the navigation tree (left)\n////////////////////////////////////////////////////////////////////////////////\n.sidebar-tree\n font-size: var(--sidebar-item-font-size)\n margin-top: var(--sidebar-tree-space-above)\n margin-bottom: var(--sidebar-item-spacing-vertical)\n\n ul\n padding: 0\n margin-top: 0\n margin-bottom: 0\n\n display: flex\n flex-direction: column\n\n list-style: none\n\n li\n position: relative\n margin: 0\n\n > ul\n margin-left: var(--sidebar-item-spacing-horizontal)\n\n .icon\n color: var(--color-sidebar-link-text)\n\n .reference\n box-sizing: border-box\n color: var(--color-sidebar-link-text)\n\n // Fill the parent.\n display: inline-block\n line-height: var(--sidebar-item-line-height)\n text-decoration: none\n\n // Don't allow long words to cause wrapping.\n overflow-wrap: anywhere\n\n height: 100%\n width: 100%\n\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n\n &:hover\n color: var(--color-sidebar-link-text)\n background: var(--color-sidebar-item-background--hover)\n\n // Add a nice little \"external-link\" arrow here.\n &.external::after\n content: url('data:image/svg+xml,')\n margin: 0 0.25rem\n vertical-align: middle\n color: var(--color-sidebar-link-text)\n\n // Make the current page reference bold.\n .current-page > .reference\n font-weight: bold\n\n label\n position: absolute\n top: 0\n right: 0\n height: var(--sidebar-item-height)\n width: var(--sidebar-expander-width)\n\n cursor: pointer\n user-select: none\n\n display: flex\n justify-content: center\n align-items: center\n\n .caption, :not(.caption) > .caption-text\n font-size: var(--sidebar-caption-font-size)\n color: var(--color-sidebar-caption-text)\n\n font-weight: bold\n text-transform: uppercase\n\n margin: var(--sidebar-caption-space-above) 0 0 0\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n\n // If it has children, add a bit more padding to wrap the content to avoid\n // overlapping with the