diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index 3a22752..0000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,125 +0,0 @@ -# ๐Ÿงฉ Contributing to This Project - -Thank you for your interest in contributing! We welcome all contributions โ€” bug reports, feature requests, pull -requests, and documentation improvements. - -Please follow the guidelines below to ensure a smooth contribution process. - ---- - -## ๐Ÿ› Reporting Bugs - -1. Check if the bug has already been reported. -2. Open a new [bug report](https://github.com/your-org/your-repo/issues/new?template=bug_report.md). -3. Include: - - Clear reproduction steps - - Expected vs. actual behavior - - Logs, screenshots, or minimal code snippets if possible - ---- - -## ๐Ÿš€ Suggesting Features - -1. Check if a similar feature request already exists. -2. Open a new [feature request](https://github.com/your-org/your-repo/issues/new?template=feature_request.md). -3. Include: - - Motivation and use case - - Desired functionality - - Alternatives you considered - ---- - -## ๐Ÿ”ง Submitting Pull Requests - -> All code changes should be proposed via Pull Request (PR) from a feature branch โ€” **do not commit directly to `main` -**. - -### Steps: - -1. Fork the repository -2. Create a new branch: - -```shell -git checkout -b feat/your-feature-name -``` - -3. Commit your changes: - -```shell -git push origin feat/your-feature-name -``` - -4. Push to your fork: - -```shell -git push origin feat/your-feature-name -``` - -5. Open a PR against the `main` branch - ---- - -## ๐Ÿ”ง Internal Code Submission Guideline - -For internal team members with write access to the repository: - -1. Always Use Feature/Fix Branches - -- Never commit directly to the main or develop branch. -- Create a new branch for each feature, bug fix. - -```shell -git checkout -b feat/your-feature-name -``` - -```shell -git checkout -b fix/your-fix-name -``` - -2. Keep Commits Clean & Meaningful - -- feat: add data loader for graph dataset -- fix: resolve crash on edge cases - -Use clear commit messages following the format: - -```shell -: -``` - -3. Test Before Pushing - -- Test your implementation in `example.py`, and compare the performance with the results in original paper. - -4. Push to Internal Branch - -- Always run `git pull origin pygip-release` before pushing your changes -- Submit a pull request targeting the `pygip-release` branch -- Write a brief summary describing the features youโ€™ve added, how to run your method, and how to evaluate its - performance - -Push to the remote feature branch. - -```shell -git push origin feat/your-feature-name -``` - ---- - -## ๐Ÿ“„ Code Style & Testing - -- Follow existing code conventions -- Use meaningful names and comments -- Add tests for new features or bug fixes -- Run all tests before submitting a PR - ---- - -## ๐Ÿ’ฌ Questions or Help? - -- Use Discussions for general questions -- Feel free to open an issue if something is unclear - ---- - -Thank you for contributing! ๐Ÿ™Œ \ No newline at end of file diff --git a/.github/IMPLEMENTATION.md b/.github/IMPLEMENTATION.md deleted file mode 100644 index 71b6e3e..0000000 --- a/.github/IMPLEMENTATION.md +++ /dev/null @@ -1,238 +0,0 @@ -## Implementation - -PyGIP is built to be modular and extensible, allowing contributors to implement their own attack and defense strategies. -Below, we detail how to extend the framework by implementing custom attack and defense classes, with a focus on how to -leverage the provided dataset structure. - -### Dataset - -The `Dataset` class standardizes the data format across PyGIP. Hereโ€™s its structure: - -```python -class Dataset(object): - def __init__(self, api_type='dgl', path='./data'): - assert api_type in {'dgl', 'pyg'}, 'API type must be dgl or pyg' - self.api_type = api_type - self.path = path - self.dataset_name = self.get_name() - - # DGLGraph or PyGData - self.graph_dataset = None - self.graph_data = None - - # meta data - self.num_nodes = 0 - self.num_features = 0 - self.num_classes = 0 -``` - -- **Importance**: We are currently using the default api_type='pyg' to load the data. It is important to note that when - api_type='pyg', `self.graph_data` should be an instance of `torch_geometric.data.Data`. In your implementation, make - sure - to use our defined Dataset class to build your code. - -### Device - -To ensure consistency and simplicity when managing CUDA devices across attacks and defenses, we follow the convention -below: - -- Both `BaseAttack` and `BaseDefense` define the device attribute `self.device` in their `__init__()` method. -- Subclasses should not manually redefine or modify the device logic. -- If you are implementing a custom attack or defense class, simply inherit from `BaseAttack` or `BaseDefense`. -- You can directly access the device using: `x = x.to(self.device)` - -### Implementing Attack - -To create a custom attack, you need to extend the abstract base class `BaseAttack`. Hereโ€™s the structure -of `BaseAttack`: - -```python -class BaseAttack(ABC): - supported_api_types = set() - supported_datasets = set() - - def __init__(self, dataset: Dataset, attack_node_fraction: float = None, model_path: str = None, - device: Optional[Union[str, torch.device]] = None): - self.device = torch.device(device) if device else get_device() - print(f"Using device: {self.device}") - - # graph data - self.dataset = dataset - self.graph_dataset = dataset.graph_dataset - self.graph_data = dataset.graph_data - - # meta data - self.num_nodes = dataset.num_nodes - self.num_features = dataset.num_features - self.num_classes = dataset.num_classes - - # params - self.attack_node_fraction = attack_node_fraction - self.model_path = model_path - - self._check_dataset_compatibility() -``` - -To implement your own attack: - -1. **Inherit from `BaseAttack`**: - Create a new class that inherits from `BaseAttack`. Youโ€™ll need to provide the following required parameters in the - constructor: - -- `dataset`: An instance of the `Dataset` class (see below for details). -- `attack_node_fraction`: A float between 0 and 1 representing the fraction of nodes to attack. -- `model_path` (optional): A string specifying the path to a pre-trained model (defaults to `None`). - -You need to implement following methods: - -- `attack()`: Add main attack logic here. If multiple attack types are supported, define the attack type as an optional - argument to this function. - For each specific attack type, implement a corresponding helper function such as `_attack_type1()` - or `_attack_type2()`, - and call the appropriate helper inside `attack()` based on the given method name. -- `_load_model()`: Load victim model. -- `_train_target_model()`: Train victim model. -- `_train_attack_model()`: Train attack model. -- `_helper_func()`(optional): Add your helper functions based on your needs, but keep the methods private. - -2. **Implement the `attack()` Method**: - Override the abstract `attack()` method with your attack logic, and return a dict of results. For example: - -```python -class MyCustomAttack(BaseAttack): - supported_api_types = {"pyg"} # "pyg" or "dgl" - supported_datasets = {"Cora"} # you can leave this blank if your method supports all datasets - - def __init__(self, dataset: Dataset, attack_node_fraction: float, model_path: str = None): - super().__init__(dataset, attack_node_fraction, model_path) - # Additional initialization if needed - - def attack(self): - # Example: Access the graph and perform an attack - print(f"Attacking {self.attack_node_fraction * 100}% of nodes") - num_nodes = self.graph.num_nodes() - print(f"Graph has {num_nodes} nodes") - # Add your attack logic here - return { - 'metric1': 'metric1 here', - 'metric2': 'metric2 here' - } - - def _load_model(self): - # add your logic here - pass - - def _train_target_model(self): - # add your logic here - pass - - def _train_attack_model(self): - # add your logic here - pass -``` - -### Implementing Defense - -To create a custom defense, you need to extend the abstract base class `BaseDefense`. Hereโ€™s the structure -of `BaseDefense`: - -```python -class BaseDefense(ABC): - supported_api_types = set() - supported_datasets = set() - - def __init__(self, dataset: Dataset, attack_node_fraction: float, - device: Optional[Union[str, torch.device]] = None): - self.device = torch.device(device) if device else get_device() - print(f"Using device: {self.device}") - - # graph data - self.dataset = dataset - self.graph_dataset = dataset.graph_dataset - self.graph_data = dataset.graph_data - - # meta data - self.num_nodes = dataset.num_nodes - self.num_features = dataset.num_features - self.num_classes = dataset.num_classes - - # params - self.attack_node_fraction = attack_node_fraction - - self._check_dataset_compatibility() -``` - -To implement your own defense: - -1. **Inherit from `BaseDefense`**: - Create a new class that inherits from `BaseDefense`. Youโ€™ll need to provide the following required parameters in the - constructor: - -- `dataset`: An instance of the `Dataset` class (see below for details). -- `attack_node_fraction`: A float between 0 and 1 representing the fraction of nodes to attack. -- `model_path` (optional): A string specifying the path to a pre-trained model (defaults to `None`). - -You need to implement following methods: - -- `defense()`: Add main defense logic here. If multiple defense types are supported, define the defense type as an - optional argument to this function. - For each specific defense type, implement a corresponding helper function such as `_defense_type1()` - or `_defense_type2()`, - and call the appropriate helper inside `defense()` based on the given method name. -- `_load_model()`: Load victim model. -- `_train_target_model()`: Train victim model. -- `_train_defense_model()`: Train defense model. -- `_train_surrogate_model()`: Train attack model. -- `_helper_func()`(optional): Add your helper functions based on your needs, but keep the methods private. - - -2. **Implement the `defense()` Method**: - Override the abstract `defense()` method with your defense logic, and return a dict of results. For example: - -```python -class MyCustomDefense(BaseDefense): - supported_api_types = {"pyg"} # "pyg" or "dgl" - supported_datasets = {"Cora"} # you can leave this blank if your method supports all datasets - - def defend(self): - # Step 1: Train target model - target_model = self._train_target_model() - # Step 2: Attack target model - attack = MyCustomAttack(self.dataset, attack_node_fraction=0.3) - attack.attack(target_model) - # Step 3: Train defense model - defense_model = self._train_defense_model() - # Step 4: Test defense against attack - attack = MyCustomAttack(self.dataset, attack_node_fraction=0.3) - attack.attack(defense_model) - # Print performance metrics - - def _load_model(self): - # add your logic here - pass - - def _train_target_model(self): - # add your logic here - pass - - def _train_defense_model(self): - # add your logic here - pass - - def _train_surrogate_model(self): - # add your logic here - pass -``` - -### Miscellaneous Tips - -- **Reference Implementation**: The `ModelExtractionAttack0` class is a fully implemented attack example. Study it for - inspiration or as a template. -- **Flexibility**: Add as many helper functions as needed within your class to keep your code clean and modular. -- **Backbone Models**: We provide several basic backbone models like `GCN, GraphSAGE`. You can use or add more - at `from models.nn import GraphSAGE`. -- **Example Scripts**: Please provide an example script in the `examples/` folder demonstrating how to run your code. This - will significantly speed up our code review process. - -By following these guidelines, you can seamlessly integrate your custom attack or defense strategies into PyGIP. Happy -coding! \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index ce8a5ba..28d3f33 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,45 +1,23 @@ --- -name: ๐Ÿ› Bug Report -about: Report a bug or unexpected behavior -title: "[Bug] " +name: Bug report +about: Report a problem with PyHazards labels: bug -assignees: '' - --- -## ๐Ÿž Describe the Bug - -A clear and concise description of what the bug is. - -## ๐Ÿ“‹ To Reproduce - -Steps to reproduce the behavior: -1. Go to '...' -2. Run '...' -3. Observe '...' - -## โœ… Expected Behavior - -A clear and concise description of what you expected to happen. +**Describe the bug** +A clear and concise description of what went wrong. -## ๐Ÿ–ผ๏ธ Screenshots or Logs +**To Reproduce** +Steps or code to reproduce the behavior. -If applicable, add screenshots or log snippets to help explain your problem. +**Expected behavior** +What you expected to happen. -## ๐Ÿงพ System Information - -Please complete the following information: -- OS: [e.g., Ubuntu 20.04 / macOS 13] -- Python version: [e.g., 3.8] -- Framework version (e.g., PyTorch, TensorFlow, etc.): -- Package version (if applicable): - -## ๐Ÿ“Ž Additional Context - -Add any other context about the problem here. - ---- +**Environment** +- Python version: +- OS: +- PyHazards version: +- Torch version: - \ No newline at end of file +**Additional context** +Add any other context, logs, or screenshots about the problem. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml deleted file mode 100644 index 4b1627d..0000000 --- a/.github/ISSUE_TEMPLATE/config.yml +++ /dev/null @@ -1,18 +0,0 @@ -blank_issues_enabled: false -contact_links: - - name: ๐Ÿ’ฌ Ask a Question - url: https://github.com/your-org/your-repo/discussions - about: Please ask and answer questions here. - -issue_templates: - - name: ๐Ÿ› Bug Report - description: Report a reproducible bug or unexpected behavior. - title: "[Bug] " - labels: [bug] - file: bug_report.md - - - name: ๐Ÿš€ Feature Request - description: Suggest a new feature or improvement. - title: "[Feature] " - labels: [enhancement] - file: feature_request.md \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 19ec93b..8660265 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,34 +1,17 @@ --- -name: ๐Ÿš€ Feature Request -about: Suggest a new feature or improvement -title: "[Feature] " +name: Feature request +about: Suggest an idea for PyHazards labels: enhancement -assignees: '' - --- -## ๐Ÿš€ Describe the Feature - -A clear and concise description of the feature you are requesting. - -## ๐Ÿ“ˆ Motivation - -Why do you need this feature? What problem does it solve or what use case does it support? - -## ๐Ÿงฉ Describe the Solution You'd Like +**Is your feature request related to a problem? Please describe.** +A clear description of the problem or user need. -Provide a clear description of what you want to happen, and how it might be implemented if you have ideas. +**Describe the solution you'd like** +What you want to add or change. -## ๐Ÿ”„ Alternatives Considered - -Have you considered any alternative approaches or solutions? If so, describe them here. - -## ๐Ÿ“Ž Additional Context - -Add any other context, mockups, or references here. - ---- +**Describe alternatives you've considered** +Any alternative solutions or workarounds. - \ No newline at end of file +**Additional context** +Any extra details, references, or examples. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index e06e22b..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,37 +0,0 @@ -# ๐Ÿ“ฆ Pull Request Template - -Thank you for your contribution! Please complete the checklist and provide relevant details below to help us review your PR effectively. - ---- - -## ๐Ÿ“‹ Summary - - - ---- - -## ๐Ÿงช Related Issues - - - ---- - -## โœ… Checklist - -- [ ] My code follows the project's coding style -- [ ] I have tested the changes and verified that they work -- [ ] I have added necessary documentation (if applicable) -- [ ] I have linked related issues above (if any) -- [ ] The PR is made from a feature branch, not `main` - ---- - -## ๐Ÿง  Additional Context (Optional) - - - ---- - - \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..0cfb85b --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,31 @@ +name: CI + +on: + push: + branches: [main, master] + pull_request: + branches: [main, master] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.10" + + - name: Install dependencies (CPU Torch) + run: | + python -m pip install --upgrade pip + python -m pip install torch --index-url https://download.pytorch.org/whl/cpu + python -m pip install -e . + + - name: Import smoke test + run: | + python - <<'PY' + import pyhazards + print("pyhazards version:", pyhazards.__version__) + PY diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index 95ae827..0000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,64 +0,0 @@ -name: build docs - -on: - push: - branches: [ main, feat/docs ] - workflow_dispatch: - -permissions: - contents: read - pages: write - id-token: write - -concurrency: - group: pages - cancel-in-progress: true - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - uses: actions/setup-python@v5 - with: - python-version: "3.8" - - - name: Install doc deps - run: | - if [ -f docs/requirements.txt ]; then - pip install -r docs/requirements.txt - else - pip install sphinx myst-parser sphinx-rtd-theme sphinx-autodoc-typehints sphinx-copybutton - fi - - - name: Install package - run: | - pip install -e . - - - name: Sanity check package discovery - run: | - python - <<'PY' - import pkgutil, pygip - print("pygip is at:", pygip.__file__) - print("submodules:", [m.name for m in pkgutil.walk_packages(pygip.__path__, pygip.__name__ + ".") if m.name.startswith("pygip.models")]) - PY - - - name: Build Sphinx html - run: | - sphinx-build -b html docs/source docs/build/html - - - name: Upload Pages artifact - uses: actions/upload-pages-artifact@v3 - with: - path: docs/build/html - - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: build - steps: - - id: deployment - uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.gitignore b/.gitignore index e0afa39..b57b888 100644 --- a/.gitignore +++ b/.gitignore @@ -1,20 +1,22 @@ -# Byte-compiled / optimized / DLL files +# Byte-compiled / cache __pycache__/ *.py[cod] -*$py.class +*.so -# build -PyGIP.egg-info/ -dist/ +# Virtual environments +.env/ +.venv/ +env/ +venv/ -# IDEs -.vscode/ -.idea/ +# Build artifacts +dist/ +build/ +*.egg-info/ -# OS +# Editor / OS .DS_Store -.AppleDouble -.LSOverride +.vscode/ -#virtual environments folder -.venv +# Docs build outputs +docs/build/ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..6d7f795 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,107 @@ +# PyHazards Architecture & Public API Sketch (Hazard-Centric) + +PyHazards targets hazard prediction (earthquake, wildfire, flood, hurricane, etc.) with an easy, batteries-included API. The design is hazard-first, GPU/multi-GPU ready, and keeps the API familiar to users of popular ML libraries. + +## Design Principles +- **Minimal onboarding**: one-liner load/train/evaluate for common hazards. +- **Backend-agnostic ML**: standard PyTorch models (tabular, image, sequence); plug-and-play custom models. +- **Hazard-aware datasets**: consistent interface across raster (remote sensing), tabular (climate/soil), time-series (buoys/stations), and vector/geospatial metadata. +- **GPU-first**: `device="auto"` everywhere; optional multi-GPU via DDP; mixed precision for speed. +- **Composable pipelines**: data โ†’ transforms โ†’ model โ†’ metrics โ†’ reporting with sensible defaults. +- **Extensible registry**: datasets, models, transforms, metrics, and pipelines are all discoverable by string names. + +## Proposed Package Layout (building on current `pyhazards/`) +- `pyhazards.datasets` + - `Dataset` base: unified API (`.load(split) -> DataBundle`, exposes `feature_spec`, `label_spec`, `splits`, `metadata`). + - `hazards/` (new): curated loaders + - `EarthquakeUSGS`, `WildfireMODIS`, `FloodCopernicus`, `HurricaneNOAA`, `LandslideNASA`, etc. + - Each handles download/cache, normalization, split logic, CRS handling for geospatial data, and returns tensors ready for models. + - `transforms/`: common preprocessing (standardize, log-scale precip, NDVI/NDWI indices, temporal windowing, patch extraction for rasters). + - `registry.py`: `load_dataset(name, split="train", cache_dir=None, **kwargs)`. +- `pyhazards.models` + - `backbones.py`: generic modules (MLP, CNN patch encoder, temporal encoder with GRU/Transformer-lite). + - `heads.py`: task heads (`ClassificationHead`, `RegressionHead`, `SegmentationHead` for raster masks). + - `builder.py`: `build_model(name="mlp"|"cnn"|"temporal", task="regression"|..., **kwargs)`. + - `registry.py`: map model names to builders + metadata (input types supported). +- `pyhazards.engine` + - `Trainer`: fit/eval/predict abstraction with callbacks, early stopping, checkpointing, mixed precision, gradient accumulation. + - `distributed`: thin wrapper for PyTorch DDP; `strategy="auto"|"ddp"|"dp"`. + - `inference.py`: batch/stream inference; sliding-window raster tiling for large scenes. +- `pyhazards.metrics` + - Classification: Acc/F1/Precision/Recall/AUROC. + - Regression: MAE/RMSE/Rยฒ. + - Segmentation: IoU/Dice. + - Calibration: ECE/Brier. +- `pyhazards.utils` + - `hardware.py`: `auto_device(prefer="cuda")`, `num_devices()`, simple device validation. + - `seed_all`, logging helpers (stdout/JSON/CSV), timer/memory profilers. +- `pyhazards.cli` + - `pyhazards run --dataset wildfire_modis --model cnn --task segmentation --device auto --strategy ddp --mixed-precision`. + +## Core Python Flow +```python +from pyhazards import datasets, models +from pyhazards.engine import Trainer +from pyhazards.metrics import RegressionMetrics +from pyhazards.utils import auto_device + +# 1) Load data +data = datasets.load("flood_copernicus", split_config="standard", cache_dir="~/.pyhazards") + +# 2) Build model +model = models.build( + name="temporal", + task="regression", + in_dim=data.feature_spec.input_dim, + out_dim=data.label_spec.num_targets, + hidden_dim=256, +) + +# 3) Train & evaluate +trainer = Trainer( + model=model, + device=auto_device(), + strategy="auto", # promotes to DDP on multi-GPU + mixed_precision=True, + metrics=[RegressionMetrics()], +) +trainer.fit(data, max_epochs=50, train_split="train", val_split="val") +results = trainer.evaluate(data, split="test") +print(results) # {"RMSE": ..., "MAE": ...} + +# 4) Predict / export +preds = trainer.predict(data, split="test") +trainer.save_checkpoint("checkpoints/flood_temporal.pt") +``` + +## CLI Flow +```bash +pyhazards run \ + --dataset earthquake_usgs \ + --model mlp \ + --task classification \ + --device auto \ + --strategy auto \ + --mixed-precision +``` + +## Data Model +- `DataBundle`: typed container with `tensors`, `splits` (`train/val/test`), `spatial_meta` (CRS, bounding boxes), `temporal_index`, and `feature_spec/label_spec`. +- Supports tabular (climate/soil), raster patches (satellite), and time-series (sensors). +- Transform pipelines apply lazily (composition over datasets) and can be reused for inference. + +## GPU & Multi-GPU +- `auto_device()` picks `cuda:0` if available else CPU; `num_devices()` detects multi-GPU. +- `Trainer(strategy="auto")`: + - Single GPU: optional AMP for speed. + - Multi-GPU: PyTorch DDP (`torchrun`) with synchronized metrics and gradient accumulation. + - CPU fallback: same API, no code changes. + +## Extensibility Checklist +- New dataset: subclass `Dataset`, implement `load(split, transforms=None)`, register via `datasets.registry`. +- New transform: add a callable, register via `datasets.transforms`. +- New model: implement `nn.Module`, expose via `models.registry` with metadata (`supported_inputs`, `task`). +- New metric: subclass `MetricBase`, add to `metrics` namespace. +- New pipeline/workflow: compose dataset + transforms + model + metrics in `pyhazards.workflows`. + +This design keeps the surface area small (load โ†’ build โ†’ train โ†’ evaluate) while being hazard-first, GPU-ready, and easy to extend as new hazards, data modalities, or models are added. diff --git a/LICENSE b/LICENSE index aac97e7..f3f4432 100644 --- a/LICENSE +++ b/LICENSE @@ -1,24 +1,21 @@ -BSD 2-Clause License +MIT License -Copyright (c) 2025 Bolin Shen +Copyright (c) 2025 Xueqi Cheng -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: +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: -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file +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. diff --git a/MANIFEST.in b/MANIFEST.in index e640dd9..f7e7587 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,9 +1,9 @@ include LICENSE include README.md -graft pygip +graft pyhazards prune .github prune tests -global-exclude __pycache__ *.py[cod] *.so *.dylib \ No newline at end of file +global-exclude __pycache__ *.py[cod] *.so *.dylib diff --git a/README.md b/README.md index 2b9fa53..0239acf 100644 --- a/README.md +++ b/README.md @@ -1,118 +1,131 @@ -# PyGIP +# PyHazards -[![PyPI - Version](https://img.shields.io/pypi/v/PyGIP)](https://pypi.org/project/PyGIP) -[![Build Status](https://img.shields.io/github/actions/workflow/status/LabRAI/PyGIP/docs.yml)](https://github.com/LabRAI/PyGIP/actions) -[![License](https://img.shields.io/github/license/LabRAI/PyGIP.svg)](https://github.com/LabRAI/PyGIP/blob/main/LICENSE) -[![PyPI - Downloads](https://img.shields.io/pypi/dm/pygip)](https://github.com/LabRAI/PyGIP) -[![Issues](https://img.shields.io/github/issues/LabRAI/PyGIP)](https://github.com/LabRAI/PyGIP) -[![Pull Requests](https://img.shields.io/github/issues-pr/LabRAI/PyGIP)](https://github.com/LabRAI/PyGIP) -[![Stars](https://img.shields.io/github/stars/LabRAI/PyGIP)](https://github.com/LabRAI/PyGIP) -[![GitHub forks](https://img.shields.io/github/forks/LabRAI/PyGIP)](https://github.com/LabRAI/PyGIP) +[![PyPI - Version](https://img.shields.io/pypi/v/pyhazards)](https://pypi.org/project/pyhazards) +[![Build Status](https://img.shields.io/github/actions/workflow/status/LabRAI/PyHazards/docs.yml)](https://github.com/LabRAI/PyHazards/actions) +[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/LabRAI/PyHazard/blob/main/LICENSE) +[![PyPI - Downloads](https://img.shields.io/pypi/dm/pyhazards)](https://pypi.org/project/pyhazards) +[![Issues](https://img.shields.io/github/issues/LabRAI/PyHazards)](https://github.com/LabRAI/PyHazards/issues) +[![Pull Requests](https://img.shields.io/github/issues-pr/LabRAI/PyHazards)](https://github.com/LabRAI/PyHazards/pulls) +[![Stars](https://img.shields.io/github/stars/LabRAI/PyHazards)](https://github.com/LabRAI/PyHazards) +[![GitHub forks](https://img.shields.io/github/forks/LabRAI/PyHazards)](https://github.com/LabRAI/PyHazards) -PyGIP is a Python library designed for experimenting with graph-based model extraction attacks and defenses. It provides -a modular framework to implement and test attack and defense strategies on graph datasets. +PyHazards is a Python framework for AI-powered hazard prediction and risk assessment. It provides a modular, hazard-first architecture for building, training, and deploying machine learning models to predict and analyze natural hazards (earthquake, wildfire, flood, hurricane, landslide, etc.). -## How to Cite - -If you find it useful, please considering cite the following work: - -```bibtex -@article{li2025intellectual, - title={Intellectual Property in Graph-Based Machine Learning as a Service: Attacks and Defenses}, - author={Li, Lincan and Shen, Bolin and Zhao, Chenxi and Sun, Yuxiang and Zhao, Kaixiang and Pan, Shirui and Dong, Yushun}, - journal={arXiv preprint arXiv:2508.19641}, - year={2025} -} -``` +## Features +- **Hazard-First Design**: Unified dataset interface for tabular, temporal, and raster data +- **Simple Models**: Ready-to-use MLP/CNN/temporal encoders with task heads (classification, regression, segmentation) +- **Trainer API**: Fit/evaluate/predict with optional mixed precision and multi-GPU (DDP) support +- **Metrics**: Built-in classification/regression/segmentation metrics +- **Extensible**: Registries for datasets, models, transforms, and pipelines ## Installation -PyGIP supports both CPU and GPU environments. Make sure you have Python installed (version >= 3.8, <3.13). +PyHazards supports both CPU and GPU environments. Make sure you have Python installed (version >= 3.8, <3.13). ### Base Installation -First, install the core package: +Install the core package: ```bash -pip install PyGIP +pip install pyhazards ``` -This will install PyGIP with minimal dependencies. +This will install PyHazards with minimal dependencies. -### CPU Version +Python 3.8 and PyTorch (CUDA 12.6 example) +----------------------------------------- -```bash -pip install "PyGIP[torch,dgl]" \ - --index-url https://download.pytorch.org/whl/cpu \ - --extra-index-url https://pypi.org/simple \ - -f https://data.dgl.ai/wheels/repo.html -``` - -### GPU Version (CUDA 12.1) +If you need a specific PyTorch build (e.g., CUDA 12.6), install PyTorch first, then install PyHazards: ```bash -pip install "PyGIP[torch,dgl]" \ - --index-url https://download.pytorch.org/whl/cu121 \ - --extra-index-url https://pypi.org/simple \ - -f https://data.dgl.ai/wheels/torch-2.3/cu121/repo.html +# Example for CUDA 12.6 wheels +pip install torch --index-url https://download.pytorch.org/whl/cu126 + +pip install pyhazards ``` ## Quick Start -Hereโ€™s a simple example to launch a Model Extraction Attack using PyGIP: +Here's a simple example to get started with PyHazards using a toy tabular dataset: ```python -from datasets import Cora -from models.attack import ModelExtractionAttack0 +import torch +from pyhazards.datasets import DataBundle, DataSplit, Dataset, FeatureSpec, LabelSpec +from pyhazards.models import build_model +from pyhazards.engine import Trainer +from pyhazards.metrics import ClassificationMetrics + +class ToyHazard(Dataset): + def _load(self): + x = torch.randn(500, 16) + y = torch.randint(0, 2, (500,)) + splits = { + "train": DataSplit(x[:350], y[:350]), + "val": DataSplit(x[350:425], y[350:425]), + "test": DataSplit(x[425:], y[425:]), + } + return DataBundle( + splits=splits, + feature_spec=FeatureSpec(input_dim=16, description="toy features"), + label_spec=LabelSpec(num_targets=2, task_type="classification"), + ) + +data = ToyHazard().load() +model = build_model(name="mlp", task="classification", in_dim=16, out_dim=2) +trainer = Trainer(model=model, metrics=[ClassificationMetrics()], mixed_precision=True) + +optimizer = torch.optim.Adam(model.parameters(), lr=1e-3) +loss_fn = torch.nn.CrossEntropyLoss() + +trainer.fit(data, optimizer=optimizer, loss_fn=loss_fn, max_epochs=5) +results = trainer.evaluate(data, split="test") +print(results) +``` -# Load the Cora dataset -dataset = Cora() +### Using CUDA -# Initialize the attack with a sampling ratio of 0.25 -mea = ModelExtractionAttack0(dataset, 0.25) +To use CUDA for GPU acceleration, set the environment variable: -# Execute the attack -mea.attack() +```shell +export PYHAZARDS_DEVICE=cuda:0 ``` -This code loads the Cora dataset, initializes a basic model extraction attack (`ModelExtractionAttack0`), and runs the -attack with a specified sampling ratio. - -And a simple example to run a Defense method against Model Extraction Attack: +Or specify the device in your code: ```python -from datasets import Cora -from models.defense import RandomWM - -# Load the Cora dataset -dataset = Cora() +from pyhazards.utils import set_device -# Initialize the attack with a sampling ratio of 0.25 -med = RandomWM(dataset, 0.25) - -# Execute the defense -med.defend() +set_device("cuda:0") ``` -which runs the Random Watermarking Graph to defend against MEA. +## Documentation -If you want to use cuda, please set environment variable: +Full documentation is available at: [https://labrai.github.io/PyHazards](https://labrai.github.io/PyHazards) -```shell -export PYGIP_DEVICE=cuda:0 -``` +## Contributing + +We welcome contributions! Please see our: +- [Implementation Guideline](.github/IMPLEMENTATION.md) - For implementing new models +- [Contributors Guideline](.github/CONTRIBUTING.md) - For contributing to the project -## Implementation & Contributors Guideline +## Citation -Refer to [Implementation Guideline](.github/IMPLEMENTATION.md) +If you use PyHazards in your research, please cite: -Refer to [Contributors Guideline](.github/CONTRIBUTING.md) +```bibtex +@software{pyhazards2025, + title={PyHazards: A Python Framework for AI-Powered Hazard Prediction}, + author={Cheng, Xueqi}, + year={2025}, + url={https://github.com/LabRAI/PyHazards} +} +``` ## License -[BSD 2-Clause License](LICENSE) +[MIT License](LICENSE) ## Contact -For questions or contributions, please contact blshen@fsu.edu. +For questions or contributions, please contact xc25@fsu.edu. diff --git a/benchmark/HOWTORUN.md b/benchmark/HOWTORUN.md deleted file mode 100644 index fde22b8..0000000 --- a/benchmark/HOWTORUN.md +++ /dev/null @@ -1,13 +0,0 @@ -chmod +x scripts/*.sh - -# RQ1: attacks (includes MEA 0..5) -bash scripts/RQ1_attacks.sh 0 - -# RQ2: defenses (best operating points) -bash scripts/RQ2_defenses.sh 0 - -# RQ3: dense sweeps for trade-off curves -bash scripts/RQ3_tradeoff.sh 0 - -# RQ4: overhead summaries -bash scripts/RQ4_overhead.sh diff --git a/benchmark/run/__init__.py b/benchmark/run/__init__.py deleted file mode 100644 index 8b13789..0000000 --- a/benchmark/run/__init__.py +++ /dev/null @@ -1 +0,0 @@ - diff --git a/benchmark/run/run_attack_track.py b/benchmark/run/run_attack_track.py deleted file mode 100644 index 8ef0b3e..0000000 --- a/benchmark/run/run_attack_track.py +++ /dev/null @@ -1,152 +0,0 @@ -# run/run_attack_track.py -import argparse -import json -import os -import traceback -from itertools import product - -# Ensure this folder is importable for `utils_benchmark` -import sys -sys.path.insert(0, os.path.dirname(__file__)) - -import torch - -from utils_benchmark import ( - load_dataset, compute_fraction_for_budget, instantiate_attack, call_attack, - write_jsonl, normalize_attack_return, timestamp, ensure_dir -) - - -def parse_args(): - p = argparse.ArgumentParser(description="GraphIP-Bench: Attack track runner (RQ1 + grid search).") - p.add_argument("--datasets", nargs="+", required=True) - p.add_argument("--attacks", nargs="+", required=True, - help="Keys: mea0 mea1 mea2 mea3 mea4 mea5 advmea cega realistic dfea_i dfea_ii dfea_iii") - p.add_argument("--budgets", nargs="+", type=float, default=[0.25, 0.5, 1.0, 2.0, 4.0]) - p.add_argument("--regimes", nargs="+", default=["both", "x_only", "a_only", "data_free"]) - p.add_argument("--seeds", nargs="+", type=int, default=[0, 1, 2]) - p.add_argument("--attack_grid_json", type=str, default=None, - help="JSON file with per-attack grids of ctor/run kwargs.") - p.add_argument("--device", type=str, default="cuda:0") - p.add_argument("--outdir", type=str, default="outputs/RQ1") - p.add_argument("--root", type=str, default=None) - p.add_argument("--dry_run", action="store_true") - return p.parse_args() - - -def regime_to_ratios(regime: str, fraction: float): - if regime == "both": - return fraction, fraction - if regime == "x_only": - return fraction, 0.0 - if regime == "a_only": - return 0.0, fraction - if regime == "data_free": - return 0.0, 0.0 - raise ValueError(f"Unknown regime: {regime}") - - -def load_attack_grid(path: str, attacks): - if not path: - return {k: [{"ctor": {}, "run": {}}] for k in attacks} - with open(path, "r", encoding="utf-8") as f: - raw = json.load(f) - grid = {} - for k in attacks: - cfgs = raw.get(k, None) - if not cfgs: - cfgs = [{"ctor": {}, "run": {}}] - norm = [] - for item in cfgs: - if "ctor" in item or "run" in item: - norm.append({"ctor": item.get("ctor", {}), "run": item.get("run", {})}) - else: - norm.append({"ctor": item, "run": {}}) - grid[k] = norm - return grid - - -def main(): - args = parse_args() - os.environ["CUDA_VISIBLE_DEVICES"] = args.device.split(":")[-1] if "cuda" in args.device else "" - ensure_dir(args.outdir) - - header = { - "runner": "attack_track", - "timestamp": timestamp(), - "datasets": args.datasets, - "attacks": args.attacks, - "budgets": args.budgets, - "regimes": args.regimes, - "seeds": args.seeds, - "device": args.device, - } - print(header) - - grid = load_attack_grid(args.attack_grid_json, args.attacks) - - for ds_name in args.datasets: - dataset = load_dataset(ds_name, root=args.root) - for budget, regime, seed, attack_key in product(args.budgets, args.regimes, args.seeds, args.attacks): - fraction = compute_fraction_for_budget(dataset, budget) - x_ratio, a_ratio = regime_to_ratios(regime, fraction) - - cfg_list = grid[attack_key] - for cfg_idx, cfg in enumerate(cfg_list): - ctor_kwargs = cfg.get("ctor", {}) - run_kwargs = cfg.get("run", {}) - - print(f"[RUN] ds={ds_name} atk={attack_key} cfg#{cfg_idx} " - f"budget={budget} frac={fraction:.5f} regime={regime} " - f"x={x_ratio:.5f} a={a_ratio:.5f} seed={seed} ctor={ctor_kwargs} run={run_kwargs}") - - if args.dry_run: - continue - - try: - torch.manual_seed(seed) - if torch.cuda.is_available(): - torch.cuda.manual_seed_all(seed) - attack = instantiate_attack(attack_key, dataset, fraction, x_ratio, a_ratio, ctor_kwargs) - perf, comp = normalize_attack_return(call_attack(attack, run_kwargs, seed)) - - record = { - "track": "attack", - "dataset": ds_name, - "attack": attack_key, - "config_index": cfg_idx, - "config": cfg, - "budget_mult": budget, - "fraction": fraction, - "regime": regime, - "attack_x_ratio": x_ratio, - "attack_a_ratio": a_ratio, - "seed": seed, - "perf": perf, - "comp": comp, - } - except Exception as e: - record = { - "track": "attack", - "dataset": ds_name, - "attack": attack_key, - "config_index": cfg_idx, - "config": cfg, - "budget_mult": budget, - "fraction": fraction, - "regime": regime, - "attack_x_ratio": x_ratio, - "attack_a_ratio": a_ratio, - "seed": seed, - "error": str(e), - "traceback": traceback.format_exc(), - } - - out_jsonl = os.path.join(args.outdir, f"{ds_name}.jsonl") - write_jsonl(out_jsonl, record) - - print(f"[DONE] Results saved to: {args.outdir}") - - -if __name__ == "__main__": - main() diff --git a/benchmark/run/run_ownership_track.py b/benchmark/run/run_ownership_track.py deleted file mode 100644 index 547823f..0000000 --- a/benchmark/run/run_ownership_track.py +++ /dev/null @@ -1,120 +0,0 @@ -# run/run_ownership_track.py -import argparse -import json -import os -import traceback -import sys - -# Ensure this folder is importable for `utils_benchmark` -sys.path.insert(0, os.path.dirname(__file__)) - -import torch - -from utils_benchmark import ( - load_dataset, instantiate_defense, call_defense, - write_jsonl, normalize_defense_return, timestamp, ensure_dir -) - - -def parse_args(): - p = argparse.ArgumentParser(description="GraphIP-Bench: Ownership track (RQ2/RQ3 + grid search).") - p.add_argument("--datasets", nargs="+", required=True) - p.add_argument("--defenses", nargs="+", required=True, - help="Keys: randomwm backdoorwm survivewm imperceptiblewm") - p.add_argument("--seeds", nargs="+", type=int, default=[0, 1, 2]) - p.add_argument("--defense_grid_json", type=str, default=None, - help="JSON file with per-defense grids of ctor/run kwargs.") - p.add_argument("--device", type=str, default="cuda:0") - p.add_argument("--outdir", type=str, default="outputs/RQ2_RQ3") - p.add_argument("--root", type=str, default=None) - p.add_argument("--dry_run", action="store_true") - return p.parse_args() - - -def load_defense_grid(path: str, defenses): - if not path: - return {k: [{"ctor": {}, "run": {}}] for k in defenses} - with open(path, "r", encoding="utf-8") as f: - raw = json.load(f) - grid = {} - for k in defenses: - cfgs = raw.get(k, None) - if not cfgs: - cfgs = [{"ctor": {}, "run": {}}] - norm = [] - for item in cfgs: - if "ctor" in item or "run" in item: - norm.append({"ctor": item.get("ctor", {}), "run": item.get("run", {})}) - else: - norm.append({"ctor": item, "run": {}}) - grid[k] = norm - return grid - - -def main(): - args = parse_args() - os.environ["CUDA_VISIBLE_DEVICES"] = args.device.split(":")[-1] if "cuda" in args.device else "" - ensure_dir(args.outdir) - - header = { - "runner": "ownership_track", - "timestamp": timestamp(), - "datasets": args.datasets, - "defenses": args.defenses, - "seeds": args.seeds, - "device": args.device, - } - print(header) - - grid = load_defense_grid(args.defense_grid_json, args.defenses) - - for ds_name in args.datasets: - dataset = load_dataset(ds_name, root=args.root) - for defense_key in args.defenses: - cfg_list = grid[defense_key] - for cfg_idx, cfg in enumerate(cfg_list): - ctor_kwargs = cfg.get("ctor", {}) - run_kwargs = cfg.get("run", {}) - for seed in args.seeds: - print(f"[RUN] ds={ds_name} defense={defense_key} cfg#{cfg_idx} ctor={ctor_kwargs} run={run_kwargs} seed={seed}") - - if args.dry_run: - continue - - try: - torch.manual_seed(seed) - if torch.cuda.is_available(): - torch.cuda.manual_seed_all(seed) - defense = instantiate_defense(defense_key, dataset, ctor_kwargs) - perf, comp = normalize_defense_return(call_defense(defense, run_kwargs, seed)) - - record = { - "track": "ownership", - "dataset": ds_name, - "defense": defense_key, - "config_index": cfg_idx, - "config": cfg, - "seed": seed, - "perf": perf, - "comp": comp, - } - except Exception as e: - record = { - "track": "ownership", - "dataset": ds_name, - "defense": defense_key, - "config_index": cfg_idx, - "config": cfg, - "seed": seed, - "error": str(e), - "traceback": traceback.format_exc(), - } - - out_jsonl = os.path.join(args.outdir, f"{ds_name}.jsonl") - write_jsonl(out_jsonl, record) - - print(f"[DONE] Results saved to: {args.outdir}") - - -if __name__ == "__main__": - main() diff --git a/benchmark/run/select_best.py b/benchmark/run/select_best.py deleted file mode 100644 index 6d1238e..0000000 --- a/benchmark/run/select_best.py +++ /dev/null @@ -1,142 +0,0 @@ -# run/select_best.py -import argparse -import glob -import json -import os -from typing import Dict, Any, List - -import pandas as pd - - -def read_jsonl(folder: str) -> List[Dict[str, Any]]: - items = [] - for p in sorted(glob.glob(os.path.join(folder, "*.jsonl"))): - with open(p, "r", encoding="utf-8") as f: - for line in f: - line = line.strip() - if line: - items.append(json.loads(line)) - return items - - -def _score_attack(perf: Dict[str, Any]) -> float: - fid = perf.get("fid", None) or perf.get("fidelity", None) - if fid is not None: - return float(fid) - acc = perf.get("acc", None) or perf.get("accuracy", None) or perf.get("test_accuracy", None) - return float(acc) if acc is not None else float("nan") - - -def _score_defense(perf: Dict[str, Any]) -> float: - fid = perf.get("fid", None) or perf.get("fidelity", None) or perf.get("post_fidelity", None) - acc = perf.get("def_acc", None) or perf.get("acc", None) or perf.get("defense_accuracy", None) - if fid is None and acc is None: - return float("nan") - if fid is None: - fid = 1.0 - if acc is None: - acc = 1.0 - return (1.0 - float(fid)) * float(acc) - - -def select_best_attack(records: List[Dict[str, Any]]): - rows = [] - for r in records: - if r.get("track") != "attack" or r.get("error"): - continue - perf = r.get("perf", {}) - score = _score_attack(perf) - row = {**r} - row["score_attack"] = score - rows.append(row) - if not rows: - return None, None - df = pd.DataFrame(rows) - keys = ["dataset", "attack", "budget_mult", "regime"] - idx = df.groupby(keys)["score_attack"].idxmax() - best_df = df.loc[idx].reset_index(drop=True) - return df, best_df - - -def select_best_defense(records: List[Dict[str, Any]]): - rows = [] - for r in records: - if r.get("track") != "ownership" or r.get("error"): - continue - perf = r.get("perf", {}) - score = _score_defense(perf) - row = {**r} - row["score_defense"] = score - rows.append(row) - if not rows: - return None, None - df = pd.DataFrame(rows) - keys = ["dataset", "defense"] - idx = df.groupby(keys)["score_defense"].idxmax() - best_df = df.loc[idx].reset_index(drop=True) - return df, best_df - - -def main(): - ap = argparse.ArgumentParser() - ap.add_argument("--rq1_dir", type=str, default="outputs/RQ1") - ap.add_argument("--rq2_dir", type=str, default="outputs/RQ2_RQ3") - ap.add_argument("--outdir", type=str, default="outputs/leaderboards") - args = ap.parse_args() - - os.makedirs(args.outdir, exist_ok=True) - - rec1 = read_jsonl(args.rq1_dir) - rec2 = read_jsonl(args.rq2_dir) - - if rec1: - full1, best1 = select_best_attack(rec1) - if full1 is not None: - full1.to_csv(os.path.join(args.outdir, "RQ1_full.csv"), index=False) - best1.to_csv(os.path.join(args.outdir, "RQ1_best.csv"), index=False) - out = {} - for _, row in best1.iterrows(): - ds = row["dataset"]; atk = row["attack"] - key = f"{ds}::{atk}::budget{row['budget_mult']}::regime{row['regime']}" - out[key] = { - "dataset": ds, - "attack": atk, - "budget_mult": row["budget_mult"], - "regime": row["regime"], - "config_index": int(row["config_index"]), - "config": row["config"], - "seed": int(row["seed"]), - "score_attack": float(row["score_attack"]), - "perf": row["perf"], - "comp": row["comp"], - } - with open(os.path.join(args.outdir, "RQ1_best_configs.json"), "w", encoding="utf-8") as f: - json.dump(out, f, indent=2) - - if rec2: - full2, best2 = select_best_defense(rec2) - if full2 is not None: - full2.to_csv(os.path.join(args.outdir, "RQ2_RQ3_full.csv"), index=False) - best2.to_csv(os.path.join(args.outdir, "RQ2_RQ3_best.csv"), index=False) - out = {} - for _, row in best2.iterrows(): - ds = row["dataset"]; d = row["defense"] - key = f"{ds}::{d}" - out[key] = { - "dataset": ds, - "defense": d, - "config_index": int(row["config_index"]), - "config": row["config"], - "seed": int(row["seed"]), - "score_defense": float(row["score_defense"]), - "perf": row["perf"], - "comp": row["comp"], - } - with open(os.path.join(args.outdir, "RQ2_RQ3_best_configs.json"), "w", encoding="utf-8") as f: - json.dump(out, f, indent=2) - - print(f"[DONE] Leaderboards written under {args.outdir}") - - -if __name__ == "__main__": - main() diff --git a/benchmark/run/to_latex.py b/benchmark/run/to_latex.py deleted file mode 100644 index 103f79f..0000000 --- a/benchmark/run/to_latex.py +++ /dev/null @@ -1,61 +0,0 @@ -# run/to_latex.py -import argparse -import json -import os -import pandas as pd - - -def to_percent(x, digits=1): - try: - return f"{float(x) * 100:.{digits}f}" - except Exception: - return "-" - - -def table_rq1(best_csv: str, out_tex: str): - df = pd.read_csv(best_csv) - keep = ["dataset", "attack", "budget_mult", "regime", "perf"] - df = df[keep].copy() - df["fid"] = df["perf"].apply(lambda s: json.loads(s.replace("'", '"')).get("fid", None) - or json.loads(s.replace("'", '"')).get("fidelity", None)) - df["acc"] = df["perf"].apply(lambda s: json.loads(s.replace("'", '"')).get("acc", None) - or json.loads(s.replace("'", '"')).get("accuracy", None) - or json.loads(s.replace("'", '"')).get("test_accuracy", None)) - df["Fidelity(%)"] = df["fid"].apply(lambda v: to_percent(v, 1)) - df["Accuracy(%)"] = df["acc"].apply(lambda v: to_percent(v, 1)) - df = df.drop(columns=["perf", "fid", "acc"]).sort_values(["dataset", "budget_mult", "regime", "attack"]) - with open(out_tex, "w", encoding="utf-8") as f: - f.write(df.to_latex(index=False, escape=False)) - print(f"[LaTeX] RQ1 table -> {out_tex}") - - -def table_rq2(best_csv: str, out_tex: str): - df = pd.read_csv(best_csv) - keep = ["dataset", "defense", "perf"] - df = df[keep].copy() - df["fid"] = df["perf"].apply(lambda s: json.loads(s.replace("'", '"')).get("fid", None) - or json.loads(s.replace("'", '"')).get("fidelity", None)) - df["def_acc"] = df["perf"].apply(lambda s: json.loads(s.replace("'", '"')).get("def_acc", None) - or json.loads(s.replace("'", '"')).get("acc", None) - or json.loads(s.replace("'", '"')).get("defense_accuracy", None)) - df["1-Fid(%)"] = df["fid"].apply(lambda v: to_percent(1.0 - float(v) if v is not None else None, 1)) - df["Utility(%)"] = df["def_acc"].apply(lambda v: to_percent(v, 1)) - df = df.drop(columns=["perf", "fid", "def_acc"]).sort_values(["dataset", "defense"]) - with open(out_tex, "w", encoding="utf-8") as f: - f.write(df.to_latex(index=False, escape=False)) - print(f"[LaTeX] RQ2/RQ3 table -> {out_tex}") - - -def main(): - ap = argparse.ArgumentParser() - ap.add_argument("--rq1_best", type=str, default="outputs/leaderboards/RQ1_best.csv") - ap.add_argument("--rq2_best", type=str, default="outputs/leaderboards/RQ2_RQ3_best.csv") - ap.add_argument("--outdir", type=str, default="outputs/leaderboards") - args = ap.parse_args() - os.makedirs(args.outdir, exist_ok=True) - table_rq1(args.rq1_best, os.path.join(args.outdir, "RQ1_best_table.tex")) - table_rq2(args.rq2_best, os.path.join(args.outdir, "RQ2_RQ3_best_table.tex")) - - -if __name__ == "__main__": - main() diff --git a/benchmark/run/utils_benchmark.py b/benchmark/run/utils_benchmark.py deleted file mode 100644 index c09a8f6..0000000 --- a/benchmark/run/utils_benchmark.py +++ /dev/null @@ -1,206 +0,0 @@ -# run/utils_benchmark.py -import importlib -import inspect -import json -import os -import sys -import time -from typing import Any, Dict, Tuple - -# Ensure repository root is on sys.path so imports like `pygip.*` always work -_REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir)) -if _REPO_ROOT not in sys.path: - sys.path.insert(0, _REPO_ROOT) - -import torch - - -def _try_import(path: str): - mod, cls = path.rsplit(".", 1) - m = importlib.import_module(mod) - return getattr(m, cls) - - -# ==== Registries (paths match your repo layout) ==== -ATTACK_REGISTRY = { - # MEA.py โ€” six attacks (0..5) - "mea0": "pygip.models.attack.mea.MEA.ModelExtractionAttack0", - "mea1": "pygip.models.attack.mea.MEA.ModelExtractionAttack1", - "mea2": "pygip.models.attack.mea.MEA.ModelExtractionAttack2", - "mea3": "pygip.models.attack.mea.MEA.ModelExtractionAttack3", - "mea4": "pygip.models.attack.mea.MEA.ModelExtractionAttack4", - "mea5": "pygip.models.attack.mea.MEA.ModelExtractionAttack5", - - # Other attacks - "advmea": "pygip.models.attack.mea.AdvMEA.AdvMEA", - "cega": "pygip.models.attack.mea.CEGA.CEGA", - "realistic": "pygip.models.attack.mea.Realistic.RealisticAttack", - "dfea_i": "pygip.models.attack.mea.DataFreeMEA.DFEATypeI", - "dfea_ii": "pygip.models.attack.mea.DataFreeMEA.DFEATypeII", - "dfea_iii": "pygip.models.attack.mea.DataFreeMEA.DFEATypeIII", -} - -DEFENSE_REGISTRY = { - "randomwm": "pygip.models.defense.atom.RandomWM.RandomWM", - "backdoorwm": "pygip.models.defense.atom.BackdoorWM.BackdoorWM", - "survivewm": "pygip.models.defense.atom.SurviveWM.SurviveWM", - "imperceptiblewm": "pygip.models.defense.atom.ImperceptibleWM.ImperceptibleWM", - # Add more if needed (e.g., GROVE) using their import paths. -} - - -def load_dataset(name: str, root: str = None): - """Robust loader that tries several known entry points.""" - tried = [] - for mod, fn in [ - ("pygip.datasets.datasets", "get_dataset"), - ("pygip.datasets", "get_dataset"), - ("pygip.data", "get_dataset"), - ("pygip.data", "build_dataset"), - ]: - try: - m = importlib.import_module(mod) - f = getattr(m, fn) - if root is None: - ds = f(name) - else: - try: - ds = f(name, root=root) - except TypeError: - ds = f(name) - return ds - except Exception as e: - tried.append(f"{mod}.{fn}: {e}") - raise RuntimeError("Could not load dataset. Tried: " + " | ".join(tried)) - - -def get_masks(dataset): - g = dataset.graph_data - n = g.number_of_nodes() if hasattr(g, "number_of_nodes") else dataset.num_nodes - nd = g.ndata - test_mask = nd["test_mask"] - train_mask = nd.get("train_mask", torch.zeros(n, dtype=torch.bool)) - val_mask = nd.get("val_mask", torch.zeros(n, dtype=torch.bool)) - return train_mask, val_mask, test_mask - - -def get_nums(dataset) -> Tuple[int, int, int]: - n = getattr(dataset, "num_nodes", None) or dataset.graph_data.number_of_nodes() - d = getattr(dataset, "num_features", None) or dataset.graph_data.ndata["feat"].shape[1] - c = getattr(dataset, "num_classes", None) or int(dataset.graph_data.ndata["label"].max().item() + 1) - return n, d, c - - -def test_size(dataset) -> int: - _, _, tmask = get_masks(dataset) - return int(tmask.sum().item()) - - -def compute_fraction_for_budget(dataset, budget_mult: float) -> float: - """Convert a test-sizeโ€“relative budget multiplier to a node fraction.""" - tsz = test_size(dataset) - n, _, _ = get_nums(dataset) - queries = max(1, int(round(budget_mult * tsz))) - return min(0.99, queries / float(n)) - - -def _has_var_kw(fn): - try: - sig = inspect.signature(fn) - for p in sig.parameters.values(): - if p.kind == inspect.Parameter.VAR_KEYWORD: - return True - return False - except (TypeError, ValueError): - return False - - -def _filter_kwargs(fn, cfg: Dict[str, Any]) -> Dict[str, Any]: - """Keep only kwargs accepted by `fn` unless it provides **kwargs.""" - if not cfg: - return {} - try: - sig = inspect.signature(fn) - except (TypeError, ValueError): - return {} - if _has_var_kw(fn): - return dict(cfg) - valid = set(sig.parameters.keys()) - return {k: v for k, v in cfg.items() if k in valid} - - -def instantiate_attack(key: str, dataset, fraction: float, x_ratio: float, a_ratio: float, ctor_kwargs: Dict[str, Any]): - cls = _try_import(ATTACK_REGISTRY[key]) - sig = inspect.signature(cls.__init__) - params = sig.parameters - if "attack_x_ratio" in params and "attack_a_ratio" in params: - safe_ctor = _filter_kwargs(cls.__init__, ctor_kwargs) - return cls(dataset=dataset, attack_x_ratio=x_ratio, attack_a_ratio=a_ratio, **safe_ctor) - if "attack_node_fraction" in params: - safe_ctor = _filter_kwargs(cls.__init__, ctor_kwargs) - return cls(dataset=dataset, attack_node_fraction=fraction, **safe_ctor) - if "attack_ratio" in params: - safe_ctor = _filter_kwargs(cls.__init__, ctor_kwargs) - return cls(dataset=dataset, attack_ratio=fraction, **safe_ctor) - safe_ctor = _filter_kwargs(cls.__init__, ctor_kwargs) - return cls(dataset=dataset, attack_node_fraction=fraction, **safe_ctor) - - -def call_attack(attack_obj, run_kwargs: Dict[str, Any], seed: int): - if not hasattr(attack_obj, "attack"): - raise RuntimeError("Attack object has no `.attack()` method.") - fn = getattr(attack_obj, "attack") - safe_run = _filter_kwargs(fn, dict(run_kwargs or {})) - safe_run["seed"] = seed - return fn(**safe_run) - - -def instantiate_defense(key: str, dataset, ctor_kwargs: Dict[str, Any]): - cls = _try_import(DEFENSE_REGISTRY[key]) - safe_ctor = _filter_kwargs(cls.__init__, ctor_kwargs or {}) - return cls(dataset=dataset, **safe_ctor) - - -def call_defense(defense_obj, run_kwargs: Dict[str, Any], seed: int): - for m in ["defend", "run", "fit", "train"]: - if hasattr(defense_obj, m) and callable(getattr(defense_obj, m)): - fn = getattr(defense_obj, m) - safe_run = _filter_kwargs(fn, dict(run_kwargs or {})) - safe_run["seed"] = seed - return fn(**safe_run) - if hasattr(defense_obj, "__call__"): - fn = getattr(defense_obj, "__call__") - safe_run = _filter_kwargs(fn, dict(run_kwargs or {})) - safe_run["seed"] = seed - return fn(**safe_run) - raise RuntimeError("No callable entrypoint found on defense object.") - - -def ensure_dir(path: str): - os.makedirs(path, exist_ok=True) - - -def write_jsonl(path: str, record: Dict[str, Any]): - ensure_dir(os.path.dirname(path)) - with open(path, "a", encoding="utf-8") as f: - f.write(json.dumps(record) + "\n") - - -def normalize_attack_return(ret) -> Tuple[Dict[str, Any], Dict[str, Any]]: - if isinstance(ret, tuple) and len(ret) == 2 and isinstance(ret[0], dict) and isinstance(ret[1], dict): - return ret[0], ret[1] - if isinstance(ret, dict): - return ret, {} - raise RuntimeError("attack.attack() did not return the expected (perf_dict, comp_dict) or dict.") - - -def normalize_defense_return(ret) -> Tuple[Dict[str, Any], Dict[str, Any]]: - if isinstance(ret, tuple) and len(ret) == 2 and isinstance(ret[0], dict) and isinstance(ret[1], dict): - return ret[0], ret[1] - if isinstance(ret, dict): - return ret, {} - raise RuntimeError("defense call did not return the expected (perf_dict, comp_dict) or dict.") - - -def timestamp() -> str: - return time.strftime("%Y-%m-%d_%H-%M-%S", time.localtime()) diff --git a/benchmark/scripts/RQ1_attacks.sh b/benchmark/scripts/RQ1_attacks.sh deleted file mode 100644 index 20565f6..0000000 --- a/benchmark/scripts/RQ1_attacks.sh +++ /dev/null @@ -1,66 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -GPU_ID="${1:-0}" - -DATASETS=("Cora" "Citeseer" "PubMed" "Amazon-Photo" "Proteins") -ATTACKS=("mea0" "mea1" "mea2" "mea3" "mea4" "mea5" "advmea" "cega" "realistic" "dfea_i" "dfea_ii" "dfea_iii") -BUDGETS=(0.25 0.5 1.0 2.0 4.0) -REGIMES=("both" "x_only" "a_only" "data_free") -SEEDS=(0 1 2) - -CONF_DIR="configs" -OUTDIR="outputs/RQ1" -LEADER_DIR="outputs/leaderboards" -mkdir -p "${CONF_DIR}" "${OUTDIR}" "${LEADER_DIR}" - -GRID_JSON="${CONF_DIR}/attack_grids_large.json" -cat > "${GRID_JSON}" <<'JSON' -{ - "mea0": [ { "ctor": {}, "run": {} } ], - "mea1": [ { "ctor": {}, "run": {} } ], - "mea2": [ { "ctor": {}, "run": {} } ], - "mea3": [ { "ctor": {}, "run": {} } ], - "mea4": [ { "ctor": {}, "run": {} } ], - "mea5": [ { "ctor": {}, "run": {} } ], - - "advmea": [ { "ctor": {}, "run": {} } ], - - "cega": [ - { "ctor": {}, "run": {"epochs_per_cycle": 1, "LR_CEGA": 0.01, "setup": "experiment"} }, - { "ctor": {}, "run": {"epochs_per_cycle": 2, "LR_CEGA": 0.01, "setup": "experiment"} }, - { "ctor": {}, "run": {"epochs_per_cycle": 1, "LR_CEGA": 0.005, "setup": "experiment"} }, - { "ctor": {}, "run": {"epochs_per_cycle": 1, "LR_CEGA": 0.01, "setup": "perturbation", "num_perturbations": 100, "noise_level": 0.05} } - ], - - "realistic": [ - { "ctor": {"hidden_dim": 32, "threshold_s": 0.60, "threshold_a": 0.40}, "run": {} }, - { "ctor": {"hidden_dim": 64, "threshold_s": 0.70, "threshold_a": 0.50}, "run": {} }, - { "ctor": {"hidden_dim": 128, "threshold_s": 0.75, "threshold_a": 0.60}, "run": {} }, - { "ctor": {"hidden_dim": 64, "threshold_s": 0.80, "threshold_a": 0.65}, "run": {} } - ], - - "dfea_i": [ { "ctor": {}, "run": {} } ], - "dfea_ii": [ { "ctor": {}, "run": {} } ], - "dfea_iii": [ { "ctor": {}, "run": {} } ] -} -JSON - -echo "[RQ1] Sweep attacks (with grids) on GPU ${GPU_ID} ..." -python run/run_attack_track.py \ - --datasets "${DATASETS[@]}" \ - --attacks "${ATTACKS[@]}" \ - --budgets "${BUDGETS[@]}" \ - --regimes "${REGIMES[@]}" \ - --seeds "${SEEDS[@]}" \ - --attack_grid_json "${GRID_JSON}" \ - --device "cuda:${GPU_ID}" \ - --outdir "${OUTDIR}" - -echo "[RQ1] Select best configs ..." -python run/select_best.py --rq1_dir "${OUTDIR}" --outdir "${LEADER_DIR}" - -echo "[RQ1] Export LaTeX tables ..." -python run/to_latex.py --outdir "${LEADER_DIR}" - -echo "[RQ1] Done. Raw -> ${OUTDIR}, Leaderboards & LaTeX -> ${LEADER_DIR}" diff --git a/benchmark/scripts/RQ2_defenses.sh b/benchmark/scripts/RQ2_defenses.sh deleted file mode 100644 index e3a3643..0000000 --- a/benchmark/scripts/RQ2_defenses.sh +++ /dev/null @@ -1,64 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -GPU_ID="${1:-0}" - -DATASETS=("Cora" "Citeseer" "PubMed" "Amazon-Photo" "Proteins") -DEFENSES=("randomwm" "backdoorwm" "survivewm" "imperceptiblewm") -SEEDS=(0 1 2) - -CONF_DIR="configs" -OUTDIR="outputs/RQ2_RQ3" -LEADER_DIR="outputs/leaderboards" -mkdir -p "${CONF_DIR}" "${OUTDIR}" "${LEADER_DIR}" - -GRID_JSON="${CONF_DIR}/defense_grids_large.json" -cat > "${GRID_JSON}" <<'JSON' -{ - "randomwm": [ - {"ctor": {"wm_ratio": 0.002}}, - {"ctor": {"wm_ratio": 0.005}}, - {"ctor": {"wm_ratio": 0.010}}, - {"ctor": {"wm_ratio": 0.020}}, - {"ctor": {"wm_ratio": 0.050}} - ], - "backdoorwm": [ - {"ctor": {"trigger_density": 0.01}}, - {"ctor": {"trigger_density": 0.02}}, - {"ctor": {"trigger_density": 0.05}}, - {"ctor": {"trigger_density": 0.10}}, - {"ctor": {"trigger_density": 0.20}} - ], - "survivewm": [ - {"ctor": {"wm_strength": 0.25}}, - {"ctor": {"wm_strength": 0.50}}, - {"ctor": {"wm_strength": 1.00}}, - {"ctor": {"wm_strength": 1.50}}, - {"ctor": {"wm_strength": 2.00}} - ], - "imperceptiblewm": [ - {"ctor": {"epsilon": 0.25}}, - {"ctor": {"epsilon": 0.50}}, - {"ctor": {"epsilon": 1.00}}, - {"ctor": {"epsilon": 2.00}}, - {"ctor": {"epsilon": 4.00}} - ] -} -JSON - -echo "[RQ2] Sweep defenses on GPU ${GPU_ID} ..." -python run/run_ownership_track.py \ - --datasets "${DATASETS[@]}" \ - --defenses "${DEFENSES[@]}" \ - --defense_grid_json "${GRID_JSON}" \ - --seeds "${SEEDS[@]}" \ - --device "cuda:${GPU_ID}" \ - --outdir "${OUTDIR}" - -echo "[RQ2] Select best configs ..." -python run/select_best.py --rq2_dir "${OUTDIR}" --outdir "${LEADER_DIR}" - -echo "[RQ2] Export LaTeX tables ..." -python run/to_latex.py --outdir "${LEADER_DIR}" - -echo "[RQ2] Done. Raw -> ${OUTDIR}, Leaderboards & LaTeX -> ${LEADER_DIR}" diff --git a/benchmark/scripts/RQ3_tradeoff.sh b/benchmark/scripts/RQ3_tradeoff.sh deleted file mode 100644 index 6f8a2d9..0000000 --- a/benchmark/scripts/RQ3_tradeoff.sh +++ /dev/null @@ -1,65 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -GPU_ID="${1:-0}" - -DATASETS=("Cora" "Citeseer" "PubMed" "Amazon-Photo" "Proteins") -DEFENSES=("randomwm" "backdoorwm" "survivewm" "imperceptiblewm") -SEEDS=(0 1 2) - -CONF_DIR="configs" -OUTDIR="outputs/RQ2_RQ3" -LEADER_DIR="outputs/leaderboards" -mkdir -p "${CONF_DIR}" "${OUTDIR}" "${LEADER_DIR}" - -GRID_JSON="${CONF_DIR}/defense_grids_dense.json" -cat > "${GRID_JSON}" <<'JSON' -{ - "randomwm": [ - {"ctor": {"wm_ratio": 0.001}}, - {"ctor": {"wm_ratio": 0.002}}, - {"ctor": {"wm_ratio": 0.005}}, - {"ctor": {"wm_ratio": 0.010}}, - {"ctor": {"wm_ratio": 0.020}}, - {"ctor": {"wm_ratio": 0.050}} - ], - "backdoorwm": [ - {"ctor": {"trigger_density": 0.005}}, - {"ctor": {"trigger_density": 0.010}}, - {"ctor": {"trigger_density": 0.020}}, - {"ctor": {"trigger_density": 0.050}}, - {"ctor": {"trigger_density": 0.100}}, - {"ctor": {"trigger_density": 0.200}} - ], - "survivewm": [ - {"ctor": {"wm_strength": 0.10}}, - {"ctor": {"wm_strength": 0.25}}, - {"ctor": {"wm_strength": 0.50}}, - {"ctor": {"wm_strength": 1.00}}, - {"ctor": {"wm_strength": 1.50}}, - {"ctor": {"wm_strength": 2.00}} - ], - "imperceptiblewm": [ - {"ctor": {"epsilon": 0.10}}, - {"ctor": {"epsilon": 0.25}}, - {"ctor": {"epsilon": 0.50}}, - {"ctor": {"epsilon": 1.00}}, - {"ctor": {"epsilon": 2.00}}, - {"ctor": {"epsilon": 4.00}} - ] -} -JSON - -echo "[RQ3] Sweep defenses densely for trade-off curves ..." -python run/run_ownership_track.py \ - --datasets "${DATASETS[@]}" \ - --defenses "${DEFENSES[@]}" \ - --defense_grid_json "${GRID_JSON}" \ - --seeds "${SEEDS[@]}" \ - --device "cuda:${GPU_ID}" \ - --outdir "${OUTDIR}" - -python run/select_best.py --rq2_dir "${OUTDIR}" --outdir "${LEADER_DIR}" -python run/to_latex.py --outdir "${LEADER_DIR}" - -echo "[RQ3] Done. Raw -> ${OUTDIR}, Leaderboards & LaTeX -> ${LEADER_DIR}" diff --git a/benchmark/scripts/RQ4_overhead.sh b/benchmark/scripts/RQ4_overhead.sh deleted file mode 100644 index b447688..0000000 --- a/benchmark/scripts/RQ4_overhead.sh +++ /dev/null @@ -1,19 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -RQ1_DIR="outputs/RQ1" -RQ2_DIR="outputs/RQ2_RQ3" -OUTDIR="outputs/RQ4_summary" -LEADER_DIR="outputs/leaderboards" -mkdir -p "${OUTDIR}" "${LEADER_DIR}" - -echo "[RQ4] Summarizing overhead ..." -python run/summarize_overhead.py \ - --rq1_dir "${RQ1_DIR}" \ - --rq2_dir "${RQ2_DIR}" \ - --outdir "${OUTDIR}" - -python run/select_best.py --rq1_dir "${RQ1_DIR}" --rq2_dir "${RQ2_DIR}" --outdir "${LEADER_DIR}" -python run/to_latex.py --outdir "${LEADER_DIR}" - -echo "[RQ4] Done. Summary CSVs -> ${OUTDIR}, Leaderboards & LaTeX -> ${LEADER_DIR}" diff --git a/examples/__init__.py b/docs/.nojekyll similarity index 100% rename from examples/__init__.py rename to docs/.nojekyll diff --git a/docs/README.md b/docs/README.md index e4cbaf1..564f20f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,9 @@ -# PyGIP Documentation +# PyHazards Documentation ## Build sphinx-build -b html source build/html +cp -r build/html/* . ## clean diff --git a/docs/_images/github.svg b/docs/_images/github.svg new file mode 100644 index 0000000..013e025 --- /dev/null +++ b/docs/_images/github.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/_modules/index.html b/docs/_modules/index.html new file mode 100644 index 0000000..d2b2080 --- /dev/null +++ b/docs/_modules/index.html @@ -0,0 +1,297 @@ + + + + + + + + + Overview: module code - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+ +
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/datasets/base.html b/docs/_modules/pyhazards/datasets/base.html new file mode 100644 index 0000000..5322ae1 --- /dev/null +++ b/docs/_modules/pyhazards/datasets/base.html @@ -0,0 +1,393 @@ + + + + + + + + + pyhazards.datasets.base - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.datasets.base

+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Protocol
+
+
+

+[docs]
+@dataclass
+class FeatureSpec:
+    """Describes input features (shapes, dtypes, normalization)."""
+    input_dim: Optional[int] = None
+    channels: Optional[int] = None
+    description: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)

+
+
+
+

+[docs]
+@dataclass
+class LabelSpec:
+    """Describes labels/targets for downstream tasks."""
+    num_targets: Optional[int] = None
+    task_type: str = "regression"  # classification|regression|segmentation
+    description: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)

+
+
+
+

+[docs]
+@dataclass
+class DataSplit:
+    """Container for a single split."""
+    inputs: Any
+    targets: Any
+    metadata: Dict[str, Any] = field(default_factory=dict)

+
+
+
+

+[docs]
+@dataclass
+class DataBundle:
+    """
+    Bundle of train/val/test splits plus metadata.
+    Keeps feature/label specs to make model construction easy.
+    """
+    splits: Dict[str, DataSplit]
+    feature_spec: FeatureSpec
+    label_spec: LabelSpec
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+

+[docs]
+    def get_split(self, name: str) -> DataSplit:
+        if name not in self.splits:
+            raise KeyError(f"Split '{name}' not found. Available: {list(self.splits.keys())}")
+        return self.splits[name]

+

+
+
+
+

+[docs]
+class Transform(Protocol):
+    """Callable data transform."""
+
+    def __call__(self, bundle: DataBundle) -> DataBundle:
+        ...

+
+
+
+

+[docs]
+class Dataset:
+    """
+    Base class for hazard datasets.
+    Subclasses should load data and return a DataBundle with splits ready for training.
+    """
+
+    name: str = "base"
+
+    def __init__(self, cache_dir: Optional[str] = None):
+        self.cache_dir = cache_dir
+
+

+[docs]
+    def load(self, split: Optional[str] = None, transforms: Optional[List[Transform]] = None) -> DataBundle:
+        """
+        Return a DataBundle. Optionally return a specific split if provided.
+        """
+        bundle = self._load()
+        if transforms:
+            for t in transforms:
+                bundle = t(bundle)
+        if split:
+            return DataBundle(
+                splits={split: bundle.get_split(split)},
+                feature_spec=bundle.feature_spec,
+                label_spec=bundle.label_spec,
+                metadata=bundle.metadata,
+            )
+        return bundle

+
+
+

+[docs]
+    def _load(self) -> DataBundle:
+        raise NotImplementedError("Subclasses must implement _load() to return a DataBundle.")

+

+
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/datasets/graph.html b/docs/_modules/pyhazards/datasets/graph.html new file mode 100644 index 0000000..3920e13 --- /dev/null +++ b/docs/_modules/pyhazards/datasets/graph.html @@ -0,0 +1,360 @@ + + + + + + + + + pyhazards.datasets.graph - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.datasets.graph

+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import torch
+from torch.utils.data import Dataset
+
+
+

+[docs]
+class GraphTemporalDataset(Dataset):
+    """
+    Simple container for county/day style tensors with an optional adjacency.
+
+    Each sample is a window of shape (past_days, num_counties, num_features) and a label
+    of shape (num_counties,).
+    """
+
+    def __init__(
+        self,
+        x: torch.Tensor,
+        y: torch.Tensor,
+        adjacency: Optional[torch.Tensor] = None,
+    ):
+        """
+        Args:
+            x: Tensor (samples, past_days, num_counties, num_features)
+            y: Tensor (samples, num_counties) or (samples, num_counties, targets)
+            adjacency: Optional Tensor
+                - (num_counties, num_counties) global adjacency
+                - (samples, num_counties, num_counties) per-sample adjacency
+        """
+        if x.ndim != 4:
+            raise ValueError("x must be (samples, past_days, num_counties, num_features)")
+        if y.ndim not in (2, 3):
+            raise ValueError("y must be (samples, num_counties) or (samples, num_counties, targets)")
+        if adjacency is not None and adjacency.ndim not in (2, 3):
+            raise ValueError("adjacency must be None, (N,N), or (B,N,N)")
+        if adjacency is not None and adjacency.ndim == 2 and adjacency.size(0) != x.size(2):
+            raise ValueError("adjacency size mismatch with num_counties")
+        if adjacency is not None and adjacency.ndim == 3 and adjacency.size(1) != x.size(2):
+            raise ValueError("adjacency size mismatch with num_counties")
+
+        self.x = x
+        self.y = y
+        self.adj = adjacency
+
+    def __len__(self) -> int:
+        return self.x.size(0)
+
+    def __getitem__(self, idx: int) -> Tuple[Dict[str, Any], torch.Tensor]:
+        adj = None
+        if self.adj is not None:
+            adj = self.adj if self.adj.ndim == 2 else self.adj[idx]
+        return {"x": self.x[idx], "adj": adj}, self.y[idx]

+
+
+
+

+[docs]
+def graph_collate(batch: List[Tuple[Dict[str, Any], torch.Tensor]]):
+    """
+    Collate function that stacks x and adjacency if provided.
+    """
+    xs, ys = zip(*batch)
+    x_tensor = torch.stack([item["x"] for item in xs], dim=0)
+    adj_list = [item["adj"] for item in xs]
+    adj = None
+    if any(a is not None for a in adj_list):
+        # If some entries are None, replace with first non-None
+        first = next(a for a in adj_list if a is not None)
+        adj = torch.stack([a if a is not None else first for a in adj_list], dim=0)
+    y_tensor = torch.stack(ys, dim=0)
+    return {"x": x_tensor, "adj": adj}, y_tensor

+
+
+
+__all__ = ["GraphTemporalDataset", "graph_collate"]
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/datasets/registry.html b/docs/_modules/pyhazards/datasets/registry.html new file mode 100644 index 0000000..b29ec2c --- /dev/null +++ b/docs/_modules/pyhazards/datasets/registry.html @@ -0,0 +1,312 @@ + + + + + + + + + pyhazards.datasets.registry - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.datasets.registry

+from typing import Any, Callable, Dict
+
+from .base import Dataset
+
+_DATASET_REGISTRY: Dict[str, Callable[..., Dataset]] = {}
+
+
+

+[docs]
+def register_dataset(name: str, builder: Callable[..., Dataset]) -> None:
+    if name in _DATASET_REGISTRY:
+        raise ValueError(f"Dataset '{name}' already registered.")
+    _DATASET_REGISTRY[name] = builder

+
+
+
+

+[docs]
+def available_datasets():
+    return sorted(_DATASET_REGISTRY.keys())

+
+
+
+

+[docs]
+def load_dataset(name: str, **kwargs: Any) -> Dataset:
+    if name not in _DATASET_REGISTRY:
+        raise KeyError(f"Dataset '{name}' is not registered. Known: {available_datasets()}")
+    return _DATASET_REGISTRY[name](**kwargs)

+
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/engine/distributed.html b/docs/_modules/pyhazards/engine/distributed.html new file mode 100644 index 0000000..a6404e6 --- /dev/null +++ b/docs/_modules/pyhazards/engine/distributed.html @@ -0,0 +1,312 @@ + + + + + + + + + pyhazards.engine.distributed - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.engine.distributed

+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import torch
+
+Strategy = Literal["auto", "ddp", "dp", "none"]
+
+
+

+[docs]
+@dataclass
+class DistributedConfig:
+    strategy: Strategy = "auto"
+    devices: int | None = None

+
+
+
+

+[docs]
+def select_strategy(prefer: Strategy = "auto") -> Strategy:
+    if prefer == "auto":
+        if torch.cuda.is_available() and torch.cuda.device_count() > 1:
+            return "ddp"
+        if torch.cuda.is_available():
+            return "none"
+        return "none"
+    return prefer

+
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/engine/inference.html b/docs/_modules/pyhazards/engine/inference.html new file mode 100644 index 0000000..5435f08 --- /dev/null +++ b/docs/_modules/pyhazards/engine/inference.html @@ -0,0 +1,311 @@ + + + + + + + + + pyhazards.engine.inference - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.engine.inference

+from __future__ import annotations
+
+from typing import Any, Callable, Iterable, List
+
+import torch
+
+
+

+[docs]
+class SlidingWindowInference:
+    """
+    Placeholder for sliding-window inference over large rasters or grids.
+    Implement windowing logic and stitching as needed.
+    """
+
+    def __init__(self, model: torch.nn.Module, window_fn: Callable[..., Iterable[Any]] | None = None):
+        self.model = model
+        self.window_fn = window_fn
+
+    def __call__(self, inputs: Any) -> List[torch.Tensor]:
+        if self.window_fn is None:
+            raise NotImplementedError("Provide a window_fn to generate windows from inputs.")
+        outputs: List[torch.Tensor] = []
+        self.model.eval()
+        with torch.no_grad():
+            for window in self.window_fn(inputs):
+                outputs.append(self.model(window))
+        return outputs

+
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/engine/trainer.html b/docs/_modules/pyhazards/engine/trainer.html new file mode 100644 index 0000000..7860dbb --- /dev/null +++ b/docs/_modules/pyhazards/engine/trainer.html @@ -0,0 +1,452 @@ + + + + + + + + + pyhazards.engine.trainer - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.engine.trainer

+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader, TensorDataset, Dataset
+
+from ..datasets.base import DataBundle
+from ..metrics import MetricBase
+from ..utils.hardware import auto_device
+from .distributed import select_strategy
+
+
+

+[docs]
+class Trainer:
+    """
+    Lightweight training abstraction with a familiar API:
+    fit -> evaluate -> predict.
+    """
+
+    def __init__(
+        self,
+        model: nn.Module,
+        device: Optional[torch.device | str] = None,
+        metrics: Optional[List[MetricBase]] = None,
+        strategy: str = "auto",
+        mixed_precision: bool = False,
+    ):
+        self.model = model
+        self.device = torch.device(device) if device else auto_device()
+        self.metrics = metrics or []
+        self.strategy = select_strategy(strategy)
+        self.mixed_precision = mixed_precision
+        self.model.to(self.device)
+
+

+[docs]
+    def fit(
+        self,
+        data: DataBundle,
+        train_split: str = "train",
+        val_split: Optional[str] = None,
+        max_epochs: int = 1,
+        optimizer: Optional[torch.optim.Optimizer] = None,
+        loss_fn: Optional[Callable[[torch.Tensor, torch.Tensor], torch.Tensor]] = None,
+        batch_size: int = 32,
+        num_workers: int = 0,
+        collate_fn: Optional[Callable[[List[Any]], Any]] = None,
+    ) -> None:
+        """
+        Minimal fit loop that works for tensor-based splits.
+        Extend/replace with custom DataLoaders for complex data.
+        """
+        if optimizer is None or loss_fn is None:
+            raise ValueError("optimizer and loss_fn must be provided.")
+
+        train_split_data = data.get_split(train_split)
+        train_loader = self._make_loader(train_split_data.inputs, train_split_data.targets, batch_size, num_workers, collate_fn)
+        scaler = torch.cuda.amp.GradScaler(enabled=self.mixed_precision and self.device.type == "cuda")
+
+        self.model.train()
+        for _ in range(max_epochs):
+            for x, y in train_loader:
+                x = self._to_device(x)
+                y = self._to_device(y)
+                optimizer.zero_grad()
+                with torch.cuda.amp.autocast(enabled=scaler.is_enabled()):
+                    out = self.model(x)
+                    loss = loss_fn(out, y)
+                scaler.scale(loss).backward()
+                scaler.step(optimizer)
+                scaler.update()
+
+        if val_split:
+            self.evaluate(data, split=val_split)

+
+
+

+[docs]
+    def evaluate(
+        self,
+        data: DataBundle,
+        split: str = "test",
+        batch_size: int = 64,
+        num_workers: int = 0,
+        collate_fn: Optional[Callable[[List[Any]], Any]] = None,
+    ) -> Dict[str, float]:
+        split_data = data.get_split(split)
+        loader = self._make_loader(split_data.inputs, split_data.targets, batch_size, num_workers, collate_fn, shuffle=False)
+        self.model.eval()
+        for metric in self.metrics:
+            metric.reset()
+        with torch.no_grad():
+            for x, y in loader:
+                x = self._to_device(x)
+                y = self._to_device(y)
+                preds = self.model(x)
+                for metric in self.metrics:
+                    metric.update(preds, y)
+        results: Dict[str, float] = {}
+        for metric in self.metrics:
+            results.update(metric.compute())
+        return results

+
+
+

+[docs]
+    def predict(
+        self,
+        data: DataBundle,
+        split: str = "test",
+        batch_size: int = 64,
+        num_workers: int = 0,
+        collate_fn: Optional[Callable[[List[Any]], Any]] = None,
+    ) -> List[torch.Tensor]:
+        split_data = data.get_split(split)
+        loader = self._make_loader(split_data.inputs, split_data.targets, batch_size, num_workers, collate_fn, shuffle=False)
+        self.model.eval()
+        outputs: List[torch.Tensor] = []
+        with torch.no_grad():
+            for x, _ in loader:
+                x = self._to_device(x)
+                preds = self.model(x)
+                outputs.append(preds.cpu())
+        return outputs

+
+
+

+[docs]
+    def save_checkpoint(self, path: str) -> None:
+        torch.save({"model_state": self.model.state_dict()}, path)

+
+
+

+[docs]
+    def _make_loader(
+        self,
+        inputs: Any,
+        targets: Any,
+        batch_size: int,
+        num_workers: int,
+        collate_fn: Optional[Callable[[List[Any]], Any]],
+        shuffle: bool = True,
+    ) -> Iterable:
+        # Accept torch tensors
+        if isinstance(inputs, torch.Tensor) and isinstance(targets, torch.Tensor):
+            dataset = TensorDataset(inputs, targets)
+            return DataLoader(dataset, batch_size=batch_size, shuffle=shuffle, num_workers=num_workers, collate_fn=collate_fn)
+        # Accept torch.utils.data.Dataset directly (for complex dict/graph batches)
+        if isinstance(inputs, Dataset):
+            return DataLoader(inputs, batch_size=batch_size, shuffle=shuffle, num_workers=num_workers, collate_fn=collate_fn)
+        raise TypeError("Trainer only supports tensor pairs or torch Dataset inputs. Wrap custom logic in a Dataset.")

+
+
+

+[docs]
+    def _to_device(self, obj: Any) -> Any:
+        if obj is None:
+            return None
+        if isinstance(obj, torch.Tensor):
+            return obj.to(self.device)
+        if isinstance(obj, (list, tuple)):
+            return type(obj)(self._to_device(o) for o in obj)
+        if isinstance(obj, dict):
+            return {k: self._to_device(v) for k, v in obj.items()}
+        return obj

+

+
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/metrics.html b/docs/_modules/pyhazards/metrics.html new file mode 100644 index 0000000..4b97cb4 --- /dev/null +++ b/docs/_modules/pyhazards/metrics.html @@ -0,0 +1,414 @@ + + + + + + + + + pyhazards.metrics - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.metrics

+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+
+import torch
+import torch.nn.functional as F
+
+
+

+[docs]
+class MetricBase(ABC):
+

+[docs]
+    @abstractmethod
+    def update(self, preds: torch.Tensor, targets: torch.Tensor) -> None:
+        ...

+
+
+

+[docs]
+    @abstractmethod
+    def compute(self) -> Dict[str, float]:
+        ...

+
+
+

+[docs]
+    @abstractmethod
+    def reset(self) -> None:
+        ...

+

+
+
+
+

+[docs]
+class ClassificationMetrics(MetricBase):
+    def __init__(self):
+        self.reset()
+
+

+[docs]
+    def reset(self) -> None:
+        self._preds: List[torch.Tensor] = []
+        self._targets: List[torch.Tensor] = []

+
+
+

+[docs]
+    def update(self, preds: torch.Tensor, targets: torch.Tensor) -> None:
+        self._preds.append(preds.detach().cpu())
+        self._targets.append(targets.detach().cpu())

+
+
+

+[docs]
+    def compute(self) -> Dict[str, float]:
+        preds = torch.cat(self._preds)
+        targets = torch.cat(self._targets)
+        pred_labels = preds.argmax(dim=-1)
+        acc = (pred_labels == targets).float().mean().item()
+        return {"Acc": acc}

+

+
+
+
+

+[docs]
+class RegressionMetrics(MetricBase):
+    def __init__(self):
+        self.reset()
+
+

+[docs]
+    def reset(self) -> None:
+        self._preds: List[torch.Tensor] = []
+        self._targets: List[torch.Tensor] = []

+
+
+

+[docs]
+    def update(self, preds: torch.Tensor, targets: torch.Tensor) -> None:
+        self._preds.append(preds.detach().cpu())
+        self._targets.append(targets.detach().cpu())

+
+
+

+[docs]
+    def compute(self) -> Dict[str, float]:
+        preds = torch.cat(self._preds)
+        targets = torch.cat(self._targets)
+        mae = F.l1_loss(preds, targets).item()
+        rmse = torch.sqrt(F.mse_loss(preds, targets)).item()
+        return {"MAE": mae, "RMSE": rmse}

+

+
+
+
+

+[docs]
+class SegmentationMetrics(MetricBase):
+    def __init__(self, num_classes: Optional[int] = None):
+        self.num_classes = num_classes
+        self.reset()
+
+

+[docs]
+    def reset(self) -> None:
+        self._preds: List[torch.Tensor] = []
+        self._targets: List[torch.Tensor] = []

+
+
+

+[docs]
+    def update(self, preds: torch.Tensor, targets: torch.Tensor) -> None:
+        self._preds.append(preds.detach().cpu())
+        self._targets.append(targets.detach().cpu())

+
+
+

+[docs]
+    def compute(self) -> Dict[str, float]:
+        preds = torch.cat(self._preds)
+        targets = torch.cat(self._targets)
+        pred_labels = preds.argmax(dim=1)
+        # simple pixel accuracy; extend to IoU/Dice as needed
+        acc = (pred_labels == targets).float().mean().item()
+        return {"PixelAcc": acc}

+

+
+
+
+__all__ = ["MetricBase", "ClassificationMetrics", "RegressionMetrics", "SegmentationMetrics"]
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/models/backbones.html b/docs/_modules/pyhazards/models/backbones.html new file mode 100644 index 0000000..9200824 --- /dev/null +++ b/docs/_modules/pyhazards/models/backbones.html @@ -0,0 +1,352 @@ + + + + + + + + + pyhazards.models.backbones - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.models.backbones

+import torch
+import torch.nn as nn
+
+
+

+[docs]
+class MLPBackbone(nn.Module):
+    """Simple MLP for tabular features."""
+
+    def __init__(self, input_dim: int, hidden_dim: int = 256, depth: int = 2):
+        super().__init__()
+        layers = []
+        dim = input_dim
+        for _ in range(depth):
+            layers.extend([nn.Linear(dim, hidden_dim), nn.ReLU()])
+            dim = hidden_dim
+        self.net = nn.Sequential(*layers)
+
+

+[docs]
+    def forward(self, x):
+        return self.net(x)

+

+
+
+
+

+[docs]
+class CNNPatchEncoder(nn.Module):
+    """Lightweight CNN encoder for raster patches."""
+
+    def __init__(self, in_channels: int = 3, hidden_dim: int = 64):
+        super().__init__()
+        self.features = nn.Sequential(
+            nn.Conv2d(in_channels, hidden_dim, kernel_size=3, padding=1),
+            nn.ReLU(),
+            nn.Conv2d(hidden_dim, hidden_dim, kernel_size=3, padding=1),
+            nn.ReLU(),
+            nn.AdaptiveAvgPool2d(1),
+        )
+
+

+[docs]
+    def forward(self, x):
+        x = self.features(x)
+        return torch.flatten(x, 1)

+

+
+
+
+

+[docs]
+class TemporalEncoder(nn.Module):
+    """GRU-based encoder for time-series signals."""
+
+    def __init__(self, input_dim: int, hidden_dim: int = 128, num_layers: int = 1):
+        super().__init__()
+        self.rnn = nn.GRU(input_dim, hidden_dim, num_layers=num_layers, batch_first=True)
+
+

+[docs]
+    def forward(self, x):
+        # x: (batch, seq, features)
+        out, _ = self.rnn(x)
+        return out[:, -1, :]

+

+
+
+
+__all__ = ["MLPBackbone", "CNNPatchEncoder", "TemporalEncoder"]
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/models/builder.html b/docs/_modules/pyhazards/models/builder.html new file mode 100644 index 0000000..9e3c245 --- /dev/null +++ b/docs/_modules/pyhazards/models/builder.html @@ -0,0 +1,353 @@ + + + + + + + + + pyhazards.models.builder - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.models.builder

+from __future__ import annotations
+
+from typing import Any, Dict
+
+import torch.nn as nn
+
+from .backbones import CNNPatchEncoder, MLPBackbone, TemporalEncoder
+from .heads import ClassificationHead, RegressionHead, SegmentationHead
+from .registry import get_model_config
+
+
+

+[docs]
+def build_model(name: str, task: str, **kwargs: Any) -> nn.Module:
+    """
+    Build a model by name and task.
+    This delegates to registry metadata to keep a consistent interface.
+    """
+    cfg = get_model_config(name)
+    if cfg is None:
+        raise KeyError(f"Model '{name}' is not registered.")
+
+    task = task.lower()
+    builder = cfg["builder"]
+    defaults: Dict[str, Any] = cfg.get("defaults", {})
+    merged = {**defaults, **kwargs, "task": task}
+    return builder(**merged)

+
+
+
+

+[docs]
+def default_builder(name: str, task: str, **kwargs: Any) -> nn.Module:
+    """
+    Generic builder for standard backbones + heads.
+    """
+    task = task.lower()
+    if name == "mlp":
+        backbone = MLPBackbone(kwargs["in_dim"], hidden_dim=kwargs.get("hidden_dim", 256), depth=kwargs.get("depth", 2))
+        head = _make_head(task, kwargs)
+        return _combine(backbone, head)
+    if name == "cnn":
+        backbone = CNNPatchEncoder(kwargs.get("in_channels", 3), hidden_dim=kwargs.get("hidden_dim", 64))
+        head = _make_head(task, kwargs, backbone_out_dim=kwargs.get("hidden_dim", 64))
+        return _combine(backbone, head)
+    if name == "temporal":
+        backbone = TemporalEncoder(kwargs["in_dim"], hidden_dim=kwargs.get("hidden_dim", 128), num_layers=kwargs.get("num_layers", 1))
+        head = _make_head(task, kwargs)
+        return _combine(backbone, head)
+    raise ValueError(f"Unknown backbone '{name}'.")

+
+
+
+def _make_head(task: str, kwargs: Dict[str, Any], backbone_out_dim: int | None = None) -> nn.Module:
+    if task == "classification":
+        in_dim = backbone_out_dim or kwargs.get("hidden_dim") or kwargs["in_dim"]
+        return ClassificationHead(in_dim=in_dim, num_classes=kwargs["out_dim"])
+    if task == "regression":
+        in_dim = backbone_out_dim or kwargs.get("hidden_dim") or kwargs["in_dim"]
+        return RegressionHead(in_dim=in_dim, out_dim=kwargs.get("out_dim", 1))
+    if task == "segmentation":
+        in_channels = kwargs.get("hidden_dim") or backbone_out_dim or kwargs.get("in_channels", 1)
+        return SegmentationHead(in_channels=in_channels, num_classes=kwargs["out_dim"])
+    raise ValueError(f"Unsupported task '{task}'.")
+
+
+def _combine(backbone: nn.Module, head: nn.Module) -> nn.Module:
+    return nn.Sequential(backbone, head)
+
+
+__all__ = ["build_model", "default_builder"]
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/models/heads.html b/docs/_modules/pyhazards/models/heads.html new file mode 100644 index 0000000..946fffd --- /dev/null +++ b/docs/_modules/pyhazards/models/heads.html @@ -0,0 +1,337 @@ + + + + + + + + + pyhazards.models.heads - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.models.heads

+import torch.nn as nn
+
+
+

+[docs]
+class ClassificationHead(nn.Module):
+    """Simple classification head."""
+
+    def __init__(self, in_dim: int, num_classes: int):
+        super().__init__()
+        self.fc = nn.Linear(in_dim, num_classes)
+
+

+[docs]
+    def forward(self, x):
+        return self.fc(x)

+

+
+
+
+

+[docs]
+class RegressionHead(nn.Module):
+    """Regression head for scalar or multi-target outputs."""
+
+    def __init__(self, in_dim: int, out_dim: int = 1):
+        super().__init__()
+        self.fc = nn.Linear(in_dim, out_dim)
+
+

+[docs]
+    def forward(self, x):
+        return self.fc(x)

+

+
+
+
+

+[docs]
+class SegmentationHead(nn.Module):
+    """Segmentation head for raster masks."""
+
+    def __init__(self, in_channels: int, num_classes: int):
+        super().__init__()
+        self.conv = nn.Conv2d(in_channels, num_classes, kernel_size=1)
+
+

+[docs]
+    def forward(self, x):
+        return self.conv(x)

+

+
+
+
+__all__ = ["ClassificationHead", "RegressionHead", "SegmentationHead"]
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/models/registry.html b/docs/_modules/pyhazards/models/registry.html new file mode 100644 index 0000000..6646352 --- /dev/null +++ b/docs/_modules/pyhazards/models/registry.html @@ -0,0 +1,313 @@ + + + + + + + + + pyhazards.models.registry - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.models.registry

+from typing import Any, Callable, Dict, Optional
+
+import torch.nn as nn
+
+_MODEL_REGISTRY: Dict[str, Dict[str, Any]] = {}
+
+
+

+[docs]
+def register_model(name: str, builder: Callable[..., nn.Module], defaults: Optional[Dict[str, Any]] = None) -> None:
+    if name in _MODEL_REGISTRY:
+        raise ValueError(f"Model '{name}' already registered.")
+    _MODEL_REGISTRY[name] = {"builder": builder, "defaults": defaults or {}}

+
+
+
+

+[docs]
+def available_models():
+    return sorted(_MODEL_REGISTRY.keys())

+
+
+
+

+[docs]
+def get_model_config(name: str) -> Optional[Dict[str, Any]]:
+    return _MODEL_REGISTRY.get(name)

+
+
+
+__all__ = ["register_model", "available_models", "get_model_config"]
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/models/wildfire_mamba.html b/docs/_modules/pyhazards/models/wildfire_mamba.html new file mode 100644 index 0000000..49ec299 --- /dev/null +++ b/docs/_modules/pyhazards/models/wildfire_mamba.html @@ -0,0 +1,536 @@ + + + + + + + + + pyhazards.models.wildfire_mamba - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.models.wildfire_mamba

+from __future__ import annotations
+
+from typing import Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+def _normalize_adjacency(adj: torch.Tensor) -> torch.Tensor:
+    """
+    Row-normalize an adjacency matrix and ensure self-loops.
+    Accepts (N, N) or (B, N, N) and returns the same rank.
+    """
+    if adj.dim() == 2:
+        adj = adj.unsqueeze(0)
+    eye = torch.eye(adj.size(-1), device=adj.device, dtype=adj.dtype)
+    adj = adj.float() + eye.unsqueeze(0)
+    return adj / adj.sum(-1, keepdim=True).clamp(min=1e-6)
+
+
+class SelectiveSSMBlock(nn.Module):
+    """
+    Lightweight selective state-space block inspired by Mamba.
+
+    Operates over a single temporal stream: (batch, time, features) -> (batch, time, hidden_dim).
+    """
+
+    def __init__(self, in_dim: int, hidden_dim: int, state_dim: int = 64, conv_kernel: int = 5, dropout: float = 0.1):
+        super().__init__()
+        self.in_proj = nn.Linear(in_dim, hidden_dim)
+        self.dwconv = nn.Conv1d(hidden_dim, hidden_dim, kernel_size=conv_kernel, padding=conv_kernel // 2, groups=hidden_dim)
+        self.gate = nn.Linear(hidden_dim, hidden_dim)
+        self.A = nn.Parameter(torch.randn(hidden_dim, state_dim) * 0.02)
+        self.B = nn.Parameter(torch.randn(state_dim, hidden_dim) * 0.02)
+        self.out_proj = nn.Linear(hidden_dim, hidden_dim)
+        self.norm = nn.LayerNorm(hidden_dim)
+        self.drop = nn.Dropout(dropout)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        # x: (B, T, F)
+        h = self.in_proj(x)  # (B, T, H)
+        h_conv = self.dwconv(h.transpose(1, 2)).transpose(1, 2)
+        g = torch.sigmoid(self.gate(h_conv))
+        B, T, H = h_conv.shape
+        state = torch.zeros(B, H, device=h_conv.device, dtype=h_conv.dtype)
+        outputs = []
+        for t in range(T):
+            # selective update: gates decide how much new signal to mix into the running state
+            state = g[:, t, :] * (state @ self.A @ self.B + h_conv[:, t, :]) + (1 - g[:, t, :]) * state
+            outputs.append(state)
+        y = torch.stack(outputs, dim=1)
+        y = self.out_proj(self.drop(y)) + h_conv
+        return self.norm(y)
+
+
+class MambaTemporalEncoder(nn.Module):
+    """Stack of selective SSM blocks; returns the last hidden state."""
+
+    def __init__(self, in_dim: int, hidden_dim: int = 128, num_layers: int = 2, state_dim: int = 64, conv_kernel: int = 5, dropout: float = 0.1):
+        super().__init__()
+        self.blocks = nn.ModuleList(
+            [
+                SelectiveSSMBlock(
+                    in_dim=in_dim if i == 0 else hidden_dim,
+                    hidden_dim=hidden_dim,
+                    state_dim=state_dim,
+                    conv_kernel=conv_kernel,
+                    dropout=dropout,
+                )
+                for i in range(num_layers)
+            ]
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        h = x
+        for block in self.blocks:
+            h = block(h)
+        return h[:, -1, :]
+
+
+class SimpleGCN(nn.Module):
+    """Two-layer GCN that mixes counties with a fixed adjacency."""
+
+    def __init__(self, in_dim: int, hidden_dim: int = 64, out_dim: int = 64, dropout: float = 0.1):
+        super().__init__()
+        self.lin1 = nn.Linear(in_dim, hidden_dim)
+        self.lin2 = nn.Linear(hidden_dim, out_dim)
+        self.drop = nn.Dropout(dropout)
+
+    def forward(self, H: torch.Tensor, adj: torch.Tensor) -> torch.Tensor:
+        # H: (B, N, D); adj: (B, N, N)
+        z = torch.matmul(adj, H)
+        z = F.relu(self.lin1(z))
+        z = self.drop(z)
+        z = torch.matmul(adj, z)
+        return F.relu(self.lin2(z))
+
+
+

+[docs]
+class WildfireMamba(nn.Module):
+    """
+    Mamba-based spatio-temporal wildfire model for county-day ERA5 features.
+
+    Input shape: (batch, past_days, num_counties, num_features)
+    Output: logits per county for the next day (use sigmoid for probabilities)
+    """
+
+    def __init__(
+        self,
+        in_dim: int,
+        num_counties: int,
+        past_days: int,
+        hidden_dim: int = 128,
+        gcn_hidden: int = 64,
+        mamba_layers: int = 2,
+        state_dim: int = 64,
+        conv_kernel: int = 5,
+        dropout: float = 0.1,
+        adjacency: Optional[torch.Tensor] = None,
+        with_count_head: bool = False,
+    ):
+        super().__init__()
+        self.num_counties = num_counties
+        self.past_days = past_days
+        self.with_count_head = with_count_head
+        self.temporal = MambaTemporalEncoder(
+            in_dim=in_dim,
+            hidden_dim=hidden_dim,
+            num_layers=mamba_layers,
+            state_dim=state_dim,
+            conv_kernel=conv_kernel,
+            dropout=dropout,
+        )
+        # differential branch is shallower and gates how much change to inject
+        self.delta_temporal = MambaTemporalEncoder(
+            in_dim=in_dim,
+            hidden_dim=hidden_dim,
+            num_layers=max(1, mamba_layers - 1),
+            state_dim=state_dim,
+            conv_kernel=conv_kernel,
+            dropout=dropout,
+        )
+        self.delta_gate = nn.Linear(hidden_dim, hidden_dim)
+        self.gcn = SimpleGCN(hidden_dim, hidden_dim=gcn_hidden, out_dim=gcn_hidden, dropout=dropout)
+        self.cls_head = nn.Linear(gcn_hidden, 1)
+        if self.with_count_head:
+            self.count_head = nn.Linear(gcn_hidden, 1)
+        self.dropout = nn.Dropout(dropout)
+        self.register_buffer("_adjacency", None)
+        if adjacency is not None:
+            self.set_adjacency(adjacency)
+
+

+[docs]
+    def set_adjacency(self, adj: torch.Tensor) -> None:
+        """Set/override the spatial adjacency."""
+        adj = _normalize_adjacency(adj.detach())
+        self._adjacency = adj

+
+
+

+[docs]
+    def _get_adjacency(self, batch_size: int) -> torch.Tensor:
+        if self._adjacency is None:
+            eye = torch.eye(self.num_counties, device=self.cls_head.weight.device)
+            adj = _normalize_adjacency(eye)
+        else:
+            adj = self._adjacency
+        if adj.dim() == 2:
+            adj = adj.unsqueeze(0)
+        if adj.size(0) == 1 and batch_size > 1:
+            adj = adj.expand(batch_size, -1, -1)
+        return adj

+
+
+

+[docs]
+    @staticmethod
+    def _temporal_delta(x: torch.Tensor) -> torch.Tensor:
+        # prepend zeros so delta has the same length as the input sequence
+        zeros = torch.zeros(x.size(0), 1, x.size(2), device=x.device, dtype=x.dtype)
+        return torch.cat([zeros, x[:, 1:] - x[:, :-1]], dim=1)

+
+
+

+[docs]
+    def forward(self, x: torch.Tensor, adjacency: Optional[torch.Tensor] = None):
+        """
+        Args:
+            x: Tensor shaped (batch, past_days, num_counties, in_dim)
+            adjacency: Optional (N, N) or (B, N, N) adjacency override.
+        Returns:
+            - logits: (batch, num_counties)
+            - optional counts: (batch, num_counties) if with_count_head is enabled.
+        """
+        B, T, N, F = x.shape
+        if T != self.past_days:
+            raise ValueError(f"Expected past_days={self.past_days}, got {T}.")
+        if N != self.num_counties:
+            raise ValueError(f"Expected num_counties={self.num_counties}, got {N}.")
+
+        # flatten counties into the batch for temporal encoding
+        x_flat = x.permute(0, 2, 1, 3).reshape(B * N, T, F)
+        base = self.temporal(x_flat)
+        delta = self.delta_temporal(self._temporal_delta(x_flat))
+        gate = torch.sigmoid(self.delta_gate(delta))
+        fused = base * gate + delta
+        fused = fused.view(B, N, -1)
+
+        adj = _normalize_adjacency(adjacency) if adjacency is not None else self._get_adjacency(B)
+        spatial = self.gcn(fused, adj)
+        spatial = self.dropout(spatial)
+        logits = self.cls_head(spatial).squeeze(-1)
+        if self.with_count_head:
+            counts = F.relu(self.count_head(spatial)).squeeze(-1)
+            return logits, counts
+        return logits

+

+
+
+
+

+[docs]
+def wildfire_mamba_builder(
+    task: str,
+    in_dim: int,
+    num_counties: int,
+    past_days: int,
+    **kwargs,
+) -> WildfireMamba:
+    """
+    Builder used by the model registry.
+    """
+    if task.lower() not in {"classification", "binary_classification"}:
+        raise ValueError("WildfireMamba is designed for binary per-county classification.")
+    return WildfireMamba(
+        in_dim=in_dim,
+        num_counties=num_counties,
+        past_days=past_days,
+        hidden_dim=kwargs.get("hidden_dim", 128),
+        gcn_hidden=kwargs.get("gcn_hidden", 64),
+        mamba_layers=kwargs.get("mamba_layers", 2),
+        state_dim=kwargs.get("state_dim", 64),
+        conv_kernel=kwargs.get("conv_kernel", 5),
+        dropout=kwargs.get("dropout", 0.1),
+        adjacency=kwargs.get("adjacency"),
+        with_count_head=kwargs.get("with_count_head", False),
+    )

+
+
+
+__all__ = ["WildfireMamba", "wildfire_mamba_builder"]
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/utils/common.html b/docs/_modules/pyhazards/utils/common.html new file mode 100644 index 0000000..c5518eb --- /dev/null +++ b/docs/_modules/pyhazards/utils/common.html @@ -0,0 +1,311 @@ + + + + + + + + + pyhazards.utils.common - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.utils.common

+import logging
+import os
+import random
+from typing import Optional
+
+import numpy as np
+import torch
+
+
+

+[docs]
+def seed_all(seed: int = 42, deterministic: bool = False) -> None:
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(seed)
+    if deterministic:
+        torch.backends.cudnn.deterministic = True
+        torch.backends.cudnn.benchmark = False

+
+
+
+

+[docs]
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    logging.basicConfig(level=os.getenv("PYHAZARD_LOGLEVEL", "INFO"))
+    return logging.getLogger(name or "pyhazards")

+
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_modules/pyhazards/utils/hardware.html b/docs/_modules/pyhazards/utils/hardware.html new file mode 100644 index 0000000..4c638e6 --- /dev/null +++ b/docs/_modules/pyhazards/utils/hardware.html @@ -0,0 +1,327 @@ + + + + + + + + + pyhazards.utils.hardware - PyHazards 1.0.1 documentation + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark, in light mode + + + + + + + + + + + + + + + Auto light/dark, in dark mode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
PyHazards 1.0.1 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+
+

Source code for pyhazards.utils.hardware

+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import torch
+
+_DEFAULT_DEVICE_STR = os.getenv("PYHAZARDS_DEVICE") or ("cuda:0" if torch.cuda.is_available() else "cpu")
+_default_device = torch.device(_DEFAULT_DEVICE_STR)
+
+
+

+[docs]
+def auto_device(prefer: str | None = None) -> torch.device:
+    """
+    Choose a device automatically. Respects PYHAZARDS_DEVICE and prefer flag.
+    """
+    if prefer:
+        return torch.device(prefer)
+    return _default_device

+
+
+
+

+[docs]
+def num_devices() -> int:
+    if torch.cuda.is_available():
+        return torch.cuda.device_count()
+    return 0

+
+
+
+

+[docs]
+def get_device() -> torch.device:
+    return _default_device

+
+
+
+

+[docs]
+def set_device(device_str: str | torch.device) -> None:
+    global _default_device
+    _default_device = torch.device(device_str)

+
+
+
+
+
+ +
+ + +
+
+
+
+ Copyright © 2025, RAILab +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + \ No newline at end of file diff --git a/docs/_sources/api/modules.rst.txt b/docs/_sources/api/modules.rst.txt new file mode 100644 index 0000000..b35db4b --- /dev/null +++ b/docs/_sources/api/modules.rst.txt @@ -0,0 +1,9 @@ +:orphan: + +pyhazards +========= + +.. toctree:: + :maxdepth: 4 + + pyhazards diff --git a/docs/_sources/api/pyhazards.datasets.rst.txt b/docs/_sources/api/pyhazards.datasets.rst.txt new file mode 100644 index 0000000..ac905d1 --- /dev/null +++ b/docs/_sources/api/pyhazards.datasets.rst.txt @@ -0,0 +1,45 @@ +pyhazards.datasets package +========================== + +Submodules +---------- + +pyhazards.datasets.base module +------------------------------ + +.. automodule:: pyhazards.datasets.base + :members: + :undoc-members: + :show-inheritance: + +pyhazards.datasets.registry module +----------------------------------- + +.. automodule:: pyhazards.datasets.registry + :members: + :undoc-members: + :show-inheritance: + +pyhazards.datasets.transforms package +------------------------------------- + +.. automodule:: pyhazards.datasets.transforms + :members: + :undoc-members: + :show-inheritance: + +pyhazards.datasets.hazards package +----------------------------------- + +.. automodule:: pyhazards.datasets.hazards + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: pyhazards.datasets + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/_sources/api/pyhazards.engine.rst.txt b/docs/_sources/api/pyhazards.engine.rst.txt new file mode 100644 index 0000000..a4ad03d --- /dev/null +++ b/docs/_sources/api/pyhazards.engine.rst.txt @@ -0,0 +1,37 @@ +pyhazards.engine package +======================== + +Submodules +---------- + +pyhazards.engine.trainer module +------------------------------- + +.. automodule:: pyhazards.engine.trainer + :members: + :undoc-members: + :show-inheritance: + +pyhazards.engine.distributed module +------------------------------------ + +.. automodule:: pyhazards.engine.distributed + :members: + :undoc-members: + :show-inheritance: + +pyhazards.engine.inference module +---------------------------------- + +.. automodule:: pyhazards.engine.inference + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: pyhazards.engine + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/_sources/api/pyhazards.metrics.rst.txt b/docs/_sources/api/pyhazards.metrics.rst.txt new file mode 100644 index 0000000..a79a09a --- /dev/null +++ b/docs/_sources/api/pyhazards.metrics.rst.txt @@ -0,0 +1,7 @@ +pyhazards.metrics package +========================= + +.. automodule:: pyhazards.metrics + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/_sources/api/pyhazards.models.rst.txt b/docs/_sources/api/pyhazards.models.rst.txt new file mode 100644 index 0000000..4e76605 --- /dev/null +++ b/docs/_sources/api/pyhazards.models.rst.txt @@ -0,0 +1,45 @@ +pyhazards.models package +======================== + +Submodules +---------- + +pyhazards.models.backbones module +---------------------------------- + +.. automodule:: pyhazards.models.backbones + :members: + :undoc-members: + :show-inheritance: + +pyhazards.models.heads module +------------------------------ + +.. automodule:: pyhazards.models.heads + :members: + :undoc-members: + :show-inheritance: + +pyhazards.models.builder module +-------------------------------- + +.. automodule:: pyhazards.models.builder + :members: + :undoc-members: + :show-inheritance: + +pyhazards.models.registry module +--------------------------------- + +.. automodule:: pyhazards.models.registry + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: pyhazards.models + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/_sources/api/pyhazards.rst.txt b/docs/_sources/api/pyhazards.rst.txt new file mode 100644 index 0000000..af00399 --- /dev/null +++ b/docs/_sources/api/pyhazards.rst.txt @@ -0,0 +1,23 @@ +pyhazards package +================= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + pyhazards.datasets + pyhazards.models + pyhazards.engine + pyhazards.metrics + pyhazards.utils + +Module contents +--------------- + +.. automodule:: pyhazards + :members: + :undoc-members: + :show-inheritance: + :exclude-members: GraphTemporalDataset, graph_collate, WildfireMamba, wildfire_mamba_builder diff --git a/docs/_sources/api/pyhazards.utils.rst.txt b/docs/_sources/api/pyhazards.utils.rst.txt new file mode 100644 index 0000000..5b552aa --- /dev/null +++ b/docs/_sources/api/pyhazards.utils.rst.txt @@ -0,0 +1,29 @@ +pyhazards.utils package +======================= + +Submodules +---------- + +pyhazards.utils.hardware module +-------------------------------- + +.. automodule:: pyhazards.utils.hardware + :members: + :undoc-members: + :show-inheritance: + +pyhazards.utils.common module +------------------------------ + +.. automodule:: pyhazards.utils.common + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: pyhazards.utils + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/_sources/cite.rst.txt b/docs/_sources/cite.rst.txt new file mode 100644 index 0000000..1e2a6ee --- /dev/null +++ b/docs/_sources/cite.rst.txt @@ -0,0 +1,12 @@ +How to Cite +=========== +If you find it useful, please considering cite the following work: + +.. .. code-block:: bibtex + +.. @article{li2025intellectual, +.. title={Intellectual Property in Graph-Based Machine Learning as a Service: Attacks and Defenses}, +.. author={Li, Lincan and Shen, Bolin and Zhao, Chenxi and Sun, Yuxiang and Zhao, Kaixiang and Pan, Shirui and Dong, Yushun}, +.. journal={arXiv preprint arXiv:2508.19641}, +.. year={2025} +.. } diff --git a/docs/_sources/implementation.rst.txt b/docs/_sources/implementation.rst.txt new file mode 100644 index 0000000..1d40f9e --- /dev/null +++ b/docs/_sources/implementation.rst.txt @@ -0,0 +1,85 @@ +Implementation Guide +==================== + +PyHazards is modular and registry-driven. This guide shows how to add your own datasets, models, transforms, and metrics in line with the hazard-first architecture. + +Datasets +-------- + +Implement a dataset by subclassing ``Dataset`` and returning a ``DataBundle`` from ``_load()``. Register it so users can load by name. + +.. code-block:: python + + import torch + from pyhazards.datasets import ( + DataBundle, DataSplit, Dataset, FeatureSpec, LabelSpec, register_dataset + ) + + class MyHazard(Dataset): + name = "my_hazard" + + def _load(self): + x = torch.randn(1000, 16) + y = torch.randint(0, 2, (1000,)) + splits = { + "train": DataSplit(x[:800], y[:800]), + "val": DataSplit(x[800:900], y[800:900]), + "test": DataSplit(x[900:], y[900:]), + } + return DataBundle( + splits=splits, + feature_spec=FeatureSpec(input_dim=16, description="example features"), + label_spec=LabelSpec(num_targets=2, task_type="classification"), + ) + + register_dataset(MyHazard.name, MyHazard) + +Transforms +---------- + +Create reusable preprocessing functions (e.g., normalization, index computation, temporal windowing) that accept and return a ``DataBundle``. Chain them via the ``transforms`` argument to ``Dataset.load()``. + +Models +------ + +Use the provided backbones (MLP, CNN patch encoder, temporal encoder) and task heads (classification, regression, segmentation) via ``build_model``. To add a custom model, register a builder: + +.. code-block:: python + + import torch.nn as nn + from pyhazards.models import register_model + + def my_model_builder(task: str, in_dim: int, out_dim: int, **kwargs) -> nn.Module: + # Simple example: a two-layer MLP for classification/regression + hidden = kwargs.get("hidden_dim", 128) + layers = nn.Sequential( + nn.Linear(in_dim, hidden), + nn.ReLU(), + nn.Linear(hidden, out_dim), + ) + return layers + + register_model("my_mlp", my_model_builder, defaults={"hidden_dim": 128}) + +Training +-------- + +Use the ``Trainer`` for fit/evaluate/predict with optional AMP and multi-GPU (DDP) support: + +.. code-block:: python + + from pyhazards.engine import Trainer + from pyhazards.metrics import ClassificationMetrics + + model = ... # build_model(...) or a registered model + trainer = Trainer(model=model, metrics=[ClassificationMetrics()], mixed_precision=True) + optimizer = torch.optim.Adam(model.parameters(), lr=1e-3) + loss_fn = torch.nn.CrossEntropyLoss() + + trainer.fit(data_bundle, optimizer=optimizer, loss_fn=loss_fn, max_epochs=10) + results = trainer.evaluate(data_bundle, split="test") + +Metrics +------- + +Metrics subclass ``MetricBase`` with ``update/compute/reset``. Add your own and pass them to ``Trainer``; for distributed training, aggregate on CPU after collecting predictions/targets. diff --git a/docs/_sources/index.rst.txt b/docs/_sources/index.rst.txt new file mode 100644 index 0000000..ab9be89 --- /dev/null +++ b/docs/_sources/index.rst.txt @@ -0,0 +1,211 @@ +.. raw:: html + +
+ PyHazards Icon +
+ +.. image:: https://img.shields.io/pypi/v/pyhazards + :target: https://pypi.org/project/pyhazards + :alt: PyPI Version + +.. image:: https://img.shields.io/github/actions/workflow/status/LabRAI/PyHazard/docs.yml + :target: https://github.com/LabRAI/PyHazard/actions + :alt: Build Status + +.. image:: https://img.shields.io/badge/license-MIT-green + :target: https://github.com/LabRAI/PyHazard/blob/main/LICENSE + :alt: License + +.. image:: https://img.shields.io/pypi/dm/pyhazards + :target: https://pypi.org/project/pyhazards + :alt: PyPI Downloads + +.. image:: https://img.shields.io/github/issues/LabRAI/PyHazard + :target: https://github.com/LabRAI/PyHazard + :alt: Issues + +.. image:: https://img.shields.io/github/issues-pr/LabRAI/PyHazard + :target: https://github.com/LabRAI/PyHazard + :alt: Pull Requests + +.. image:: https://img.shields.io/github/stars/LabRAI/PyHazard + :target: https://github.com/LabRAI/PyHazard + :alt: Stars + +.. image:: https://img.shields.io/github/forks/LabRAI/PyHazard + :target: https://github.com/LabRAI/PyHazard + :alt: GitHub forks + +.. image:: _static/github.svg + :target: https://github.com/LabRAI/PyHazards + :alt: GitHub + +---- + +**PyHazards** is a comprehensive Python framework for AI-powered hazard prediction and risk assessment. Built on PyTorch with a hazard-first design, the library provides a modular and extensible architecture for building, training, and deploying machine learning models to predict and analyze natural hazards and environmental risks. + +**PyHazards is designed for:** + +- **Hazard-First Architecture**: Unified dataset interface for tabular, temporal, and raster data +- **Simple, Extensible Models**: Ready-to-use MLP/CNN/temporal encoders with task heads +- **Trainer API**: Fit/evaluate/predict with optional mixed precision and multi-GPU (DDP) support +- **Metrics**: Classification, regression, and segmentation metrics out of the box +- **Extensibility**: Registries for datasets, models, transforms, and pipelines + +**Quick Start Example:** + +Basic Usage Example (toy dataset): + +.. code-block:: python + + import torch + from pyhazards.datasets import DataBundle, DataSplit, Dataset, FeatureSpec, LabelSpec + from pyhazards.models import build_model + from pyhazards.engine import Trainer + from pyhazards.metrics import ClassificationMetrics + + class ToyHazard(Dataset): + def _load(self): + x = torch.randn(500, 16) + y = torch.randint(0, 2, (500,)) + splits = { + "train": DataSplit(x[:350], y[:350]), + "val": DataSplit(x[350:425], y[350:425]), + "test": DataSplit(x[425:], y[425:]), + } + return DataBundle( + splits=splits, + feature_spec=FeatureSpec(input_dim=16, description="toy features"), + label_spec=LabelSpec(num_targets=2, task_type="classification"), + ) + + data = ToyHazard().load() + model = build_model(name="mlp", task="classification", in_dim=16, out_dim=2) + trainer = Trainer(model=model, metrics=[ClassificationMetrics()], mixed_precision=True) + + optimizer = torch.optim.Adam(model.parameters(), lr=1e-3) + loss_fn = torch.nn.CrossEntropyLoss() + + trainer.fit(data, optimizer=optimizer, loss_fn=loss_fn, max_epochs=5) + results = trainer.evaluate(data, split="test") + print(results) + +Wildfire Mamba (spatio-temporal toy) +------------------------------------ + +Mamba-style county/day wildfire model with a graph-aware Dataset and collate. + +.. code-block:: python + + import torch + from pyhazards.datasets import DataBundle, DataSplit, FeatureSpec, LabelSpec, GraphTemporalDataset, graph_collate + from pyhazards.engine import Trainer + from pyhazards.models import build_model + + past_days = 8 + num_counties = 4 + num_features = 6 + samples = 32 + + # Fake county/day ERA5-like tensor and binary fire labels + x = torch.randn(samples, past_days, num_counties, num_features) + y = torch.randint(0, 2, (samples, num_counties)).float() + adjacency = torch.eye(num_counties) # replace with distance/correlation matrix + + train_ds = GraphTemporalDataset(x[:24], y[:24], adjacency=adjacency) + val_ds = GraphTemporalDataset(x[24:], y[24:], adjacency=adjacency) + + bundle = DataBundle( + splits={ + "train": DataSplit(train_ds, None), + "val": DataSplit(val_ds, None), + }, + feature_spec=FeatureSpec(input_dim=num_features, extra={"past_days": past_days, "counties": num_counties}), + label_spec=LabelSpec(num_targets=num_counties, task_type="classification"), + ) + + model = build_model( + name="wildfire_mamba", + task="classification", + in_dim=num_features, + num_counties=num_counties, + past_days=past_days, + adjacency=adjacency, + ) + + trainer = Trainer(model=model, mixed_precision=False) + optimizer = torch.optim.Adam(model.parameters(), lr=1e-3) + loss_fn = torch.nn.BCEWithLogitsLoss() + + trainer.fit(bundle, optimizer=optimizer, loss_fn=loss_fn, max_epochs=2, batch_size=4, collate_fn=graph_collate) + + # Next-day fire probabilities for one window + with torch.no_grad(): + logits = model(x[:1]) + probs = torch.sigmoid(logits) + print(probs.shape) # (1, num_counties) + +Core Components +--------------- + +**Datasets** + PyHazards provides a unified dataset interface for tabular, temporal, and raster data, returning a ``DataBundle`` with splits and specs. + +**Models** + Extensible model architecture with MLP/CNN/temporal backbones and task heads for classification, regression, and segmentation. + Easy to implement and register custom models via the model registry. + +**Utilities** + Helper functions for device management, seeding/logging, and metrics calculation. + +How to Cite +----------- + +If you use PyHazards in your research, please cite: + +.. code-block:: bibtex + + @software{pyhazards2025, + title={PyHazards: A Python Framework for AI-Powered Hazard Prediction}, + author={Cheng, Xueqi}, + year={2025}, + url={https://github.com/LabRAI/PyHazards} + } + + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + :hidden: + + installation + quick_start + +.. toctree:: + :maxdepth: 1 + :caption: API Reference + :hidden: + + pyhazards_datasets + pyhazards_models + pyhazards_engine + pyhazards_metrics + pyhazards_utils + +.. toctree:: + :maxdepth: 2 + :caption: Additional Information + :hidden: + + implementation + cite + references + team + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/_sources/installation.rst.txt b/docs/_sources/installation.rst.txt new file mode 100644 index 0000000..6ea4bc6 --- /dev/null +++ b/docs/_sources/installation.rst.txt @@ -0,0 +1,31 @@ +Installation +============ + +PyHazards requires Python 3.8+ and can be installed using pip. We recommend using a conda environment for installation. + +Installing PyHazards +-------------------- + +Base install: + +.. code-block:: bash + + pip install pyhazards + +PyTorch notes (Python 3.8, CUDA 12.6 example): + +- Install the matching PyTorch wheel first, then install PyHazards. +- Example (CUDA 12.6): + + .. code-block:: bash + + pip install torch --index-url https://download.pytorch.org/whl/cu126 + pip install pyhazards + + + +Requirements +------------ + +- Python >= 3.8 +- PyTorch == 2.3.0 diff --git a/docs/_sources/pyhazards_datasets.rst.txt b/docs/_sources/pyhazards_datasets.rst.txt new file mode 100644 index 0000000..36c376b --- /dev/null +++ b/docs/_sources/pyhazards_datasets.rst.txt @@ -0,0 +1,65 @@ +Datasets +=================== + +Summary +------- + +PyHazards provides a unified dataset interface for hazard prediction across tabular, temporal, and raster data. Each dataset returns a ``DataBundle`` containing splits, feature specs, label specs, and metadata. + +Datasets +-------------------- + +.. list-table:: + :widths: 18 82 + :header-rows: 0 + :class: dataset-list + + * - ``MERRA-2`` + - MERRA-2 is a global weather and climate dataset created by NASA that provides long-term records of atmospheric conditions from 1980 to the present. The data are organized on a regular global grid with hourly to monthly updates and a spatial resolution of about 0.5ยฐ ร— 0.625ยฐ, and include variables such as temperature, wind, humidity, surface fluxes, and aerosols, making it useful for large-scale climate and hazard analysis worldwide. + * - ``ERA5`` + - ERA5 is a global reanalysis dataset produced by ECMWF and is commonly used as a reference for weather and climate studies. It covers the period from 1950 to the present and provides hourly data on a global grid at roughly 0.25ยฐ resolution, including precipitation, temperature, wind, and land-surface variables, which allows detailed environmental and hazard modeling at a global scale. + * - ``NOAA Flood Events (Storm Events Database)`` + - The NOAA Flood Events dataset collects reported flood events across the United States, including when and where floods occurred and the impacts they caused. The data are stored as event-based records rather than grid data, usually at county or local levels, and span many decades, making them suitable for analyzing flood patterns and risks within the U.S. + * - ``FIRMS (Fire Information for Resource Management System)`` + - FIRMS (Fire Information for Resource Management System) provides near-real-time satellite observations of active fires around the world. The dataset consists of time-stamped fire locations detected by MODIS and VIIRS sensors at spatial resolutions between about 375 m and 1 km, and is widely used for global wildfire monitoring and analysis. + * - ``MTBS (Monitoring Trends in Burn Severity)`` + - MTBS (Monitoring Trends in Burn Severity) is a dataset that maps wildfire burn areas and severity across the United States. It focuses on large fires since 1984 and uses Landsat satellite imagery at 30 m resolution, making it useful for studying long-term wildfire impacts and regional fire risk. + * - ``LANDFIRE Fuel (USFS / LANDFIRE)`` + - LANDFIRE provides fuel and vegetation information across the United States to support wildfire modeling and risk assessment. The data are distributed as raster layers at about 30 m resolution and describe fuel models, canopy structure, and vegetation types, helping researchers and practitioners understand and simulate wildfire behavior at landscape scales. + +Core classes +------------ + +- ``Dataset``: base class to implement ``_load()`` and return a ``DataBundle``. +- ``DataBundle``: holds named ``DataSplit`` objects, plus ``feature_spec`` and ``label_spec``. +- ``FeatureSpec`` / ``LabelSpec``: describe inputs/targets to simplify model construction. +- ``register_dataset`` / ``load_dataset``: lightweight registry for discovering datasets by name. + +Example skeleton +---------------- + +.. code-block:: python + + import torch + from pyhazards.datasets import ( + DataBundle, DataSplit, Dataset, FeatureSpec, LabelSpec, register_dataset + ) + + class MyHazardDataset(Dataset): + name = "my_hazard" + + def _load(self): + x = torch.randn(1000, 16) + y = torch.randint(0, 2, (1000,)) + splits = { + "train": DataSplit(x[:800], y[:800]), + "val": DataSplit(x[800:900], y[800:900]), + "test": DataSplit(x[900:], y[900:]), + } + return DataBundle( + splits=splits, + feature_spec=FeatureSpec(input_dim=16, description="example features"), + label_spec=LabelSpec(num_targets=2, task_type="classification"), + ) + + register_dataset(MyHazardDataset.name, MyHazardDataset) diff --git a/docs/_sources/pyhazards_engine.rst.txt b/docs/_sources/pyhazards_engine.rst.txt new file mode 100644 index 0000000..5dc091d --- /dev/null +++ b/docs/_sources/pyhazards_engine.rst.txt @@ -0,0 +1,41 @@ +Engine +=================== + +Summary +------- + +The engine wraps training/evaluation/prediction with sensible defaults and optional distributed support. + +Core modules +------------ + +- ``pyhazards.engine.trainer`` โ€” ``Trainer`` class with ``fit``, ``evaluate``, ``predict``, checkpoint save. +- ``pyhazards.engine.distributed`` โ€” strategy selection and config helpers. +- ``pyhazards.engine.inference`` โ€” sliding-window inference placeholder for large rasters/grids. + +Typical usage +------------- + +.. code-block:: python + + import torch + from pyhazards.engine import Trainer + from pyhazards.metrics import ClassificationMetrics + from pyhazards.models import build_model + + model = build_model(name="mlp", task="classification", in_dim=16, out_dim=2) + trainer = Trainer(model=model, metrics=[ClassificationMetrics()], mixed_precision=True) + + optimizer = torch.optim.Adam(model.parameters(), lr=1e-3) + loss_fn = torch.nn.CrossEntropyLoss() + + trainer.fit(data_bundle, optimizer=optimizer, loss_fn=loss_fn, max_epochs=10) + results = trainer.evaluate(data_bundle, split="test") + preds = trainer.predict(data_bundle, split="test") + +Distributed and devices +----------------------- + +- ``Trainer(strategy="auto")`` uses DDP when multiple GPUs are available; otherwise runs single-device. +- ``mixed_precision=True`` enables AMP when on CUDA. +- Device selection is handled via ``pyhazards.utils.hardware.auto_device`` by default. diff --git a/docs/_sources/pyhazards_metrics.rst.txt b/docs/_sources/pyhazards_metrics.rst.txt new file mode 100644 index 0000000..10fde92 --- /dev/null +++ b/docs/_sources/pyhazards_metrics.rst.txt @@ -0,0 +1,27 @@ +Metrics +=================== + +Summary +------- + +Built-in metrics cover common tasks and are designed to aggregate predictions/targets over a full split. + +Core classes +------------ + +- ``MetricBase`` โ€” abstract interface with ``update``, ``compute``, ``reset``. +- ``ClassificationMetrics`` โ€” accuracy. +- ``RegressionMetrics`` โ€” MAE, RMSE. +- ``SegmentationMetrics`` โ€” pixel accuracy (extend to IoU/Dice as needed). + +Usage +----- + +.. code-block:: python + + from pyhazards.metrics import ClassificationMetrics + + metrics = [ClassificationMetrics()] + # pass to Trainer or call directly + +*** End Patch ***! diff --git a/docs/_sources/pyhazards_models.rst.txt b/docs/_sources/pyhazards_models.rst.txt new file mode 100644 index 0000000..3f5566e --- /dev/null +++ b/docs/_sources/pyhazards_models.rst.txt @@ -0,0 +1,129 @@ +Models +=================== + +Summary +------- + +PyHazards provides a lightweight, extensible model architecture with: + +- Backbones for common data types: MLP (tabular), CNN patch encoder (raster), temporal encoder (time-series). +- Task heads: classification, regression, segmentation. +- A registry-driven builder so you can construct built-ins by name or register your own. + +Core modules +------------ + +- ``pyhazards.models.backbones`` โ€” reusable feature extractors. +- ``pyhazards.models.heads`` โ€” task-specific heads. +- ``pyhazards.models.builder`` โ€” ``build_model(name, task, **kwargs)`` helper plus ``default_builder``. +- ``pyhazards.models.registry`` โ€” ``register_model`` / ``available_models``. +- ``pyhazards.models`` โ€” convenience re-exports and default registrations for ``mlp``, ``cnn``, ``temporal``. + +Build a built-in model +---------------------- + +.. code-block:: python + + from pyhazards.models import build_model + + model = build_model( + name="mlp", + task="classification", + in_dim=32, + out_dim=5, + hidden_dim=256, + depth=3, + ) + +Register a custom model +----------------------- + +Create a builder function that returns an ``nn.Module`` and register it with a name. The registry handles defaults and discoverability. + +.. code-block:: python + + import torch.nn as nn + from pyhazards.models import register_model, build_model + + def my_custom_builder(task: str, in_dim: int, out_dim: int, **kwargs) -> nn.Module: + hidden = kwargs.get("hidden_dim", 128) + layers = nn.Sequential( + nn.Linear(in_dim, hidden), + nn.ReLU(), + nn.Linear(hidden, out_dim), + ) + return layers + + register_model("my_mlp", my_custom_builder, defaults={"hidden_dim": 128}) + + model = build_model(name="my_mlp", task="regression", in_dim=16, out_dim=1) + +Mamba-based wildfire model (spatio-temporal) +-------------------------------------------- + +PyHazards ships a Mamba-style spatio-temporal model for county-day wildfire prediction using ERA5 features. It couples a selective state-space temporal encoder with a lightweight GCN to mix neighboring counties. + +- Input: ``(batch, past_days, num_counties, num_features)`` county-day ERA5 tensors. +- Temporal: stacked selective SSM blocks plus a differential branch to highlight day-to-day changes. +- Spatial: two-layer GCN over a provided adjacency (falls back to identity if none is given). +- Output: per-county logits for the next day (apply ``torch.sigmoid`` for probabilities). Optional count head via ``with_count_head=True``. + +Toy usage with random ERA5-like tensors: + +.. code-block:: python + + import torch + from pyhazards.datasets import DataBundle, DataSplit, FeatureSpec, LabelSpec + from pyhazards.engine import Trainer + from pyhazards.models import build_model + + past_days = 12 + num_counties = 5 + num_features = 6 # e.g., t2m, d2m, u10, v10, tp, ssr + samples = 64 + + # Fake county-day ERA5 cube and binary fire labels + x = torch.randn(samples, past_days, num_counties, num_features) + y = torch.randint(0, 2, (samples, num_counties)).float() + adjacency = torch.eye(num_counties) # replace with a distance or correlation matrix + + bundle = DataBundle( + splits={ + "train": DataSplit(x[:48], y[:48]), + "val": DataSplit(x[48:], y[48:]), + }, + feature_spec=FeatureSpec(input_dim=num_features, extra={"past_days": past_days, "counties": num_counties}), + label_spec=LabelSpec(num_targets=num_counties, task_type="classification"), + ) + + model = build_model( + name="wildfire_mamba", + task="classification", + in_dim=num_features, + num_counties=num_counties, + past_days=past_days, + adjacency=adjacency, + ) + + trainer = Trainer(model=model, mixed_precision=False) + optimizer = torch.optim.Adam(model.parameters(), lr=1e-3) + loss_fn = torch.nn.BCEWithLogitsLoss() + + # Fit on the toy data; Trainer works because inputs/targets are plain tensors + trainer.fit(bundle, optimizer=optimizer, loss_fn=loss_fn, max_epochs=2, batch_size=8) + + # Predict probabilities for the next day + with torch.no_grad(): + logits = model(x[:1]) + probs = torch.sigmoid(logits) + print(probs.shape) # (1, num_counties) + + # For more complex batches (dicts with adjacency), wrap tensors in GraphTemporalDataset + # and pass graph_collate to Trainer.fit/evaluate/predict. + +Design notes +------------ + +- Builders receive ``task`` plus any kwargs you pass; use this to switch heads internally if needed. +- ``register_model`` stores optional defaults so you can keep CLI/configs minimal. +- Models are plain PyTorch modules, so you can compose them with the ``Trainer`` or your own loops. diff --git a/docs/_sources/pyhazards_utils.rst.txt b/docs/_sources/pyhazards_utils.rst.txt new file mode 100644 index 0000000..6430e53 --- /dev/null +++ b/docs/_sources/pyhazards_utils.rst.txt @@ -0,0 +1,13 @@ +Utils +=================== + +Summary +------- + +Utility modules for device management, seeding, logging, and other helpers. + +Submodules +---------- + +- :mod:`pyhazards.utils.hardware` โ€” device helpers +- :mod:`pyhazards.utils.common` โ€” seeding and logging helpers diff --git a/docs/_sources/quick_start.rst.txt b/docs/_sources/quick_start.rst.txt new file mode 100644 index 0000000..f05b5b7 --- /dev/null +++ b/docs/_sources/quick_start.rst.txt @@ -0,0 +1,75 @@ +Quick Start +================= +This guide will help you get started with PyHazards quickly using the hazard-first API. + +Basic Usage +----------- + +Toy Example (tabular classification) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + import torch + from pyhazards.datasets import DataBundle, DataSplit, Dataset, FeatureSpec, LabelSpec + from pyhazards.models import build_model + from pyhazards.engine import Trainer + from pyhazards.metrics import ClassificationMetrics + + class ToyHazard(Dataset): + def _load(self): + x = torch.randn(500, 16) + y = torch.randint(0, 2, (500,)) + splits = { + "train": DataSplit(x[:350], y[:350]), + "val": DataSplit(x[350:425], y[350:425]), + "test": DataSplit(x[425:], y[425:]), + } + return DataBundle( + splits=splits, + feature_spec=FeatureSpec(input_dim=16, description="toy features"), + label_spec=LabelSpec(num_targets=2, task_type="classification"), + ) + + data = ToyHazard().load() + model = build_model(name="mlp", task="classification", in_dim=16, out_dim=2) + trainer = Trainer(model=model, metrics=[ClassificationMetrics()], mixed_precision=True) + + optimizer = torch.optim.Adam(model.parameters(), lr=1e-3) + loss_fn = torch.nn.CrossEntropyLoss() + + trainer.fit(data, optimizer=optimizer, loss_fn=loss_fn, max_epochs=5) + results = trainer.evaluate(data, split="test") + print(results) + +GPU Support +----------- + +PyHazards automatically detects CUDA availability. To explicitly set the device: + +**Using Environment Variable:** + +.. code-block:: bash + + export PYHAZARDS_DEVICE=cuda:0 + +**Using Python API:** + +.. code-block:: python + + from pyhazards.utils import set_device + + # Set to use CUDA device 0 + set_device("cuda:0") + + # Or use CPU + set_device("cpu") + +Next Steps +---------- + +For more detailed documentation, please refer to: + +- :doc:`pyhazards_datasets` - Dataset interface and registration +- :doc:`pyhazards_utils` - Utility functions and helpers +- :doc:`implementation` - Guide for implementing custom datasets and models diff --git a/docs/_sources/references.rst.txt b/docs/_sources/references.rst.txt new file mode 100644 index 0000000..818a674 --- /dev/null +++ b/docs/_sources/references.rst.txt @@ -0,0 +1,6 @@ +References +========== + +Academic Publications +--------------------- + diff --git a/docs/_sources/team.rst.txt b/docs/_sources/team.rst.txt new file mode 100644 index 0000000..b9f46b8 --- /dev/null +++ b/docs/_sources/team.rst.txt @@ -0,0 +1,45 @@ +Core Team +========= + +Our team is composed of dedicated researchers and developers who contribute to PyHazards's development and maintenance. + +Lead Developer +-------------- +* Xueqi Cheng - Florida State University (xc25@fsu.edu) + +Contributors +------------ +* `Yushun Dong `__ - Florida State University + +Principal Contributors & Maintainers +------------------------------------ +.. * `Yuxiang Sun `__ - University of Wisconsin-Madison +.. * `Chenxi Zhao `__ - Northeastern University +.. * `Lincan Li `__ - Florida State University + +Core Contributors +----------------- +.. * `Unique Karki `_ - [Affiliation] +.. * `Yujing Ju `__ - Heriot-Watt University +.. * `Zhan Cheng `__ - University of Wisconsin-Madison +.. * `Zaiyi Zheng `__ - University of Virginia +.. * `Tyler Blalock `_ - [Affiliation] +.. * `Sibtain Syed `_ - [Affiliation] +.. * `Md Ibrahim `_ - Uttara University, Bangladesh +.. * `Aditya Khanal `_ - Tribhuvan University, Nepal +.. * `Kedar Satish Awale `_ - Florida State University +.. * `Hong Iris `_ - Washington University in St. Louis +.. * `Aasman Bashyal `_ - [Affiliation] +.. * `Cameron Bender `_ - Florida State University +.. * `Yushi Huang `_ - [Affiliation] +.. * `Anurag Shukla `_ - [Affiliation] + + +---------------- + +The Core Team is responsible for: + +* Strategic planning and technical direction +* Code review and quality assurance +* Documentation and maintenance +* Community engagement and support diff --git a/docs/_static/basic.css b/docs/_static/basic.css new file mode 100644 index 0000000..4738b2e --- /dev/null +++ b/docs/_static/basic.css @@ -0,0 +1,906 @@ +/* + * 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; +} + +/* -- 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/docs/_static/debug.css b/docs/_static/debug.css new file mode 100644 index 0000000..74d4aec --- /dev/null +++ b/docs/_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/docs/_static/doctools.js b/docs/_static/doctools.js new file mode 100644 index 0000000..0398ebb --- /dev/null +++ b/docs/_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/docs/_static/documentation_options.js b/docs/_static/documentation_options.js new file mode 100644 index 0000000..aaba30f --- /dev/null +++ b/docs/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '1.0.1', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: true, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/docs/_static/file.png b/docs/_static/file.png new file mode 100644 index 0000000..a858a41 Binary files /dev/null and b/docs/_static/file.png differ diff --git a/docs/_static/github.svg b/docs/_static/github.svg new file mode 100644 index 0000000..013e025 --- /dev/null +++ b/docs/_static/github.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/_static/language_data.js b/docs/_static/language_data.js new file mode 100644 index 0000000..c7fe6c6 --- /dev/null +++ b/docs/_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/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 0000000..3a7451e Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/_static/minus.png b/docs/_static/minus.png new file mode 100644 index 0000000..d96755f Binary files /dev/null and b/docs/_static/minus.png differ diff --git a/docs/_static/plus.png b/docs/_static/plus.png new file mode 100644 index 0000000..7107cec Binary files /dev/null and b/docs/_static/plus.png differ diff --git a/docs/_static/pygments.css b/docs/_static/pygments.css new file mode 100644 index 0000000..9d1083b --- /dev/null +++ b/docs/_static/pygments.css @@ -0,0 +1,250 @@ +.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: #fdf2e2 } +.highlight { background: #f2f2f2; color: #1E1E1E } +.highlight .c { color: #515151 } /* Comment */ +.highlight .err { color: #D71835 } /* Error */ +.highlight .k { color: #8045E5 } /* Keyword */ +.highlight .l { color: #7F4707 } /* Literal */ +.highlight .n { color: #1E1E1E } /* Name */ +.highlight .o { color: #163 } /* Operator */ +.highlight .p { color: #1E1E1E } /* Punctuation */ +.highlight .ch { color: #515151 } /* Comment.Hashbang */ +.highlight .cm { color: #515151 } /* Comment.Multiline */ +.highlight .cp { color: #515151 } /* Comment.Preproc */ +.highlight .cpf { color: #515151 } /* Comment.PreprocFile */ +.highlight .c1 { color: #515151 } /* Comment.Single */ +.highlight .cs { color: #515151 } /* Comment.Special */ +.highlight .gd { color: #00749C } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gh { color: #00749C } /* Generic.Heading */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #00749C } /* Generic.Subheading */ +.highlight .kc { color: #8045E5 } /* Keyword.Constant */ +.highlight .kd { color: #8045E5 } /* Keyword.Declaration */ +.highlight .kn { color: #8045E5 } /* Keyword.Namespace */ +.highlight .kp { color: #8045E5 } /* Keyword.Pseudo */ +.highlight .kr { color: #8045E5 } /* Keyword.Reserved */ +.highlight .kt { color: #7F4707 } /* Keyword.Type */ +.highlight .ld { color: #7F4707 } /* Literal.Date */ +.highlight .m { color: #7F4707 } /* Literal.Number */ +.highlight .s { color: #163 } /* Literal.String */ +.highlight .na { color: #7F4707 } /* Name.Attribute */ +.highlight .nb { color: #7F4707 } /* Name.Builtin */ +.highlight .nc { color: #00749C } /* Name.Class */ +.highlight .no { color: #00749C } /* Name.Constant */ +.highlight .nd { color: #7F4707 } /* Name.Decorator */ +.highlight .ni { color: #163 } /* Name.Entity */ +.highlight .ne { color: #8045E5 } /* Name.Exception */ +.highlight .nf { color: #00749C } /* Name.Function */ +.highlight .nl { color: #7F4707 } /* Name.Label */ +.highlight .nn { color: #1E1E1E } /* Name.Namespace */ +.highlight .nx { color: #1E1E1E } /* Name.Other */ +.highlight .py { color: #00749C } /* Name.Property */ +.highlight .nt { color: #00749C } /* Name.Tag */ +.highlight .nv { color: #D71835 } /* Name.Variable */ +.highlight .ow { color: #8045E5 } /* Operator.Word */ +.highlight .pm { color: #1E1E1E } /* Punctuation.Marker */ +.highlight .w { color: #1E1E1E } /* Text.Whitespace */ +.highlight .mb { color: #7F4707 } /* Literal.Number.Bin */ +.highlight .mf { color: #7F4707 } /* Literal.Number.Float */ +.highlight .mh { color: #7F4707 } /* Literal.Number.Hex */ +.highlight .mi { color: #7F4707 } /* Literal.Number.Integer */ +.highlight .mo { color: #7F4707 } /* Literal.Number.Oct */ +.highlight .sa { color: #163 } /* Literal.String.Affix */ +.highlight .sb { color: #163 } /* Literal.String.Backtick */ +.highlight .sc { color: #163 } /* Literal.String.Char */ +.highlight .dl { color: #163 } /* Literal.String.Delimiter */ +.highlight .sd { color: #163 } /* Literal.String.Doc */ +.highlight .s2 { color: #163 } /* Literal.String.Double */ +.highlight .se { color: #163 } /* Literal.String.Escape */ +.highlight .sh { color: #163 } /* Literal.String.Heredoc */ +.highlight .si { color: #163 } /* Literal.String.Interpol */ +.highlight .sx { color: #163 } /* Literal.String.Other */ +.highlight .sr { color: #D71835 } /* Literal.String.Regex */ +.highlight .s1 { color: #163 } /* Literal.String.Single */ +.highlight .ss { color: #00749C } /* Literal.String.Symbol */ +.highlight .bp { color: #7F4707 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #00749C } /* Name.Function.Magic */ +.highlight .vc { color: #D71835 } /* Name.Variable.Class */ +.highlight .vg { color: #D71835 } /* Name.Variable.Global */ +.highlight .vi { color: #D71835 } /* Name.Variable.Instance */ +.highlight .vm { color: #7F4707 } /* Name.Variable.Magic */ +.highlight .il { color: #7F4707 } /* 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: #FFF; font-weight: bold } /* Generic.Heading */ +body[data-theme="dark"] .highlight .gi { color: #589819 } /* Generic.Inserted */ +body[data-theme="dark"] .highlight .go { color: #CCC } /* Generic.Output */ +body[data-theme="dark"] .highlight .gp { color: #AAA } /* Generic.Prompt */ +body[data-theme="dark"] .highlight .gs { color: #D0D0D0; font-weight: bold } /* Generic.Strong */ +body[data-theme="dark"] .highlight .gu { color: #FFF; 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: #BBB } /* 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: #BBB } /* 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: #666 } /* 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: #FFF; font-weight: bold } /* Generic.Heading */ +body:not([data-theme="light"]) .highlight .gi { color: #589819 } /* Generic.Inserted */ +body:not([data-theme="light"]) .highlight .go { color: #CCC } /* Generic.Output */ +body:not([data-theme="light"]) .highlight .gp { color: #AAA } /* Generic.Prompt */ +body:not([data-theme="light"]) .highlight .gs { color: #D0D0D0; font-weight: bold } /* Generic.Strong */ +body:not([data-theme="light"]) .highlight .gu { color: #FFF; 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: #BBB } /* 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: #BBB } /* 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: #666 } /* 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/examples/attack/__init__.py b/docs/_static/scripts/furo-extensions.js similarity index 100% rename from examples/attack/__init__.py rename to docs/_static/scripts/furo-extensions.js diff --git a/docs/_static/scripts/furo.js b/docs/_static/scripts/furo.js new file mode 100644 index 0000000..87e1767 --- /dev/null +++ b/docs/_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;function s(){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 l(){!function(){const t=document.getElementsByClassName("theme-toggle");Array.from(t).forEach(t=>{t.addEventListener("click",s)})}(),function(){let t=0,e=!1;window.addEventListener("scroll",function(n){t=window.scrollY,e||(window.requestAnimationFrame(function(){var n;(function(t){t>0?r.classList.add("scrolled"):r.classList.remove("scrolled")})(n=t),function(t){t<64?document.documentElement.classList.remove("show-back-to-top"):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);const e=r.getBoundingClientRect();return e.top+e.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"),l()})})()})(); +//# sourceMappingURL=furo.js.map \ No newline at end of file diff --git a/docs/_static/scripts/furo.js.LICENSE.txt b/docs/_static/scripts/furo.js.LICENSE.txt new file mode 100644 index 0000000..1632189 --- /dev/null +++ b/docs/_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/docs/_static/scripts/furo.js.map b/docs/_static/scripts/furo.js.map new file mode 100644 index 0000000..3b316f3 --- /dev/null +++ b/docs/_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,KAAK,SAAUC,EAAOC,GAG7B,OAFcR,EAAaO,EAAME,SACnBT,EAAaQ,EAAMC,UACF,EACxB,CACT,EAEJ,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,EAAU,SAAUjB,GAE/C,IAAIxB,EAAUS,SAASyC,eACrBC,mBAAmB3B,EAAK4B,KAAKC,OAAO,KAEjCrD,GAGLJ,EAAS0D,KAAK,CACZ1B,IAAKJ,EACLxB,QAASA,GAEb,GAGAL,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,sBAAsB,WACrChE,EAAaC,GACbgD,EAAWgB,QACb,EACF,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,UAAW,SAAUC,GAChD,IAAK,IAAIC,KAAOD,EAAK,CACnB,IAAKA,EAAIE,eAAeD,GAAM,OAC9BH,EAAOG,GAAOD,EAAIC,EACpB,CACF,GACOH,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,oB,GCXDwG,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,GCLRR,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,MCJ3EO,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,G,yCCK9EC,EAAY,KACZC,EAAS,KACTC,EAAgBzF,SAASC,gBAAgByF,UA4E7C,SAASC,IACP,MAAMC,EAAeC,aAAaC,QAAQ,UAAY,OAZxD,IAAkBC,EACH,WADGA,EAaIrI,OAAOsI,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,QAGT/F,SAASS,KAAK2F,QAAQC,MAAQN,EAC9BF,aAAaS,QAAQ,QAASP,GAC9BG,QAAQK,IAAI,cAAcR,UA0B5B,CAmDA,SAASlC,KART,WAEE,MAAM2C,EAAUxG,SAASyG,uBAAuB,gBAChDpE,MAAMqE,KAAKF,GAASjE,QAASoE,IAC3BA,EAAI7C,iBAAiB,QAAS6B,IAElC,CAGEiB,GA/CF,WAEE,IAAIC,EAA6B,EAC7BC,GAAU,EAEdpJ,OAAOoG,iBAAiB,SAAU,SAAUuB,GAC1CwB,EAA6BnJ,OAAOqJ,QAE/BD,IACHpJ,OAAOwF,sBAAsB,WAzDnC,IAAuB8D,GArDvB,SAAgCA,GAC1BA,EAAY,EACdxB,EAAOjE,UAAUM,IAAI,YAErB2D,EAAOjE,UAAUC,OAAO,WAE5B,EAgDEyF,CADqBD,EA0DDH,GAvGtB,SAAmCG,GAC7BA,EAXmB,GAYrBhH,SAASC,gBAAgBsB,UAAUC,OAAO,oBAEtCwF,EAAYvB,EACdzF,SAASC,gBAAgBsB,UAAUM,IAAI,oBAC9BmF,EAAYvB,GACrBzF,SAASC,gBAAgBsB,UAAUC,OAAO,oBAG9CiE,EAAgBuB,CAClB,CAoCEE,CAA0BF,GAlC5B,SAA6BA,GACT,OAAdzB,IAKa,GAAbyB,EACFzB,EAAU4B,SAAS,EAAG,GAGtB9G,KAAKC,KAAK0G,IACV3G,KAAK+G,MAAMpH,SAASC,gBAAgBS,aAAehD,OAAOqC,aAE1DwF,EAAU4B,SAAS,EAAG5B,EAAU7E,cAGhBV,SAASqH,cAAc,mBAc3C,CAKEC,CAAoBN,GAwDdF,GAAU,CACZ,GAEAA,GAAU,EAEd,GACApJ,OAAO6J,QACT,CA8BEC,GA3BkB,OAAdjC,GAKJ,IAAI,IAAJ,CAAY,cAAe,CACzBrH,QAAQ,EACRuJ,WAAW,EACX5J,SAAU,iBACVI,OAAQ,KACN,IAAIyJ,EAAM9H,WAAW+H,iBAAiB3H,SAASC,iBAAiB2H,UAChE,MAAMC,EAAarC,EAAO7F,wBAC1B,OAAOkI,EAAW1H,IAAM0H,EAAWC,OAAS,IAAMJ,EAAM,IAiB9D,CAcA1H,SAAS8D,iBAAiB,mBAT1B,WACE9D,SAASS,KAAKW,WAAWG,UAAUC,OAAO,SAE1CgE,EAASxF,SAASqH,cAAc,UAChC9B,EAAYvF,SAASqH,cAAc,eAEnCxD,GACF,E","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 if (positionY > 0) {\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 const headerRect = header.getBoundingClientRect();\n return headerRect.top + headerRect.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","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","scrollHandlerForHeader","scrollHandlerForBackToTop","scrollTo","floor","querySelector","scrollHandlerForTOC","scroll","setupScrollHandler","recursive","rem","getComputedStyle","fontSize","headerRect","height"],"sourceRoot":""} \ No newline at end of file diff --git a/docs/_static/searchtools.js b/docs/_static/searchtools.js new file mode 100644 index 0000000..91f4be5 --- /dev/null +++ b/docs/_static/searchtools.js @@ -0,0 +1,635 @@ +/* + * 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 = []; + // find documents, if any, containing the query word in their text/title term indices + // use Object.hasOwnProperty to avoid mismatching against prototype properties + const arr = [ + { files: terms.hasOwnProperty(word) ? terms[word] : undefined, score: Scorer.term }, + { files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined, 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, new Map()); + const fileScores = scoreMap.get(file); + fileScores.set(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).get(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/docs/_static/skeleton.css b/docs/_static/skeleton.css new file mode 100644 index 0000000..467c878 --- /dev/null +++ b/docs/_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/docs/_static/sphinx_highlight.js b/docs/_static/sphinx_highlight.js new file mode 100644 index 0000000..8a96c69 --- /dev/null +++ b/docs/_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/docs/_static/styles/furo-extensions.css b/docs/_static/styles/furo-extensions.css new file mode 100644 index 0000000..2d74267 --- /dev/null +++ b/docs/_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 0s}.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/docs/_static/styles/furo-extensions.css.map b/docs/_static/styles/furo-extensions.css.map new file mode 100644 index 0000000..68fb7fd --- /dev/null +++ b/docs/_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,mBACA,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/docs/_static/styles/furo.css b/docs/_static/styles/furo.css new file mode 100644 index 0000000..592d5bf --- /dev/null +++ b/docs/_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}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 0s,height 0s,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]>.highlight{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/docs/_static/styles/furo.css.map b/docs/_static/styles/furo.css.map new file mode 100644 index 0000000..280b3fe --- /dev/null +++ b/docs/_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,aCPF,KCCE,mHAGA,wGAGA,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,CCnCxC,+FAIA,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,CCRjC,+jBCaA,iqCAZF,iaCXA,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,sCL3HF,kCAEA,sDAIA,0CKyHE,kEAIA,oDACA,sDAGA,oCACA,oEAEA,0DACA,qDAIA,oDACA,6DAIA,iEAIA,2DAIA,2DAGA,4DACA,gEAIA,gEAEA,gFAEA,oNASA,qDLtKE,gFAGE,4DAIF,oEKgHF,yEAEA,6DAGA,0DAEA,uDACA,qDACA,wDAIA,6DAIA,yDACA,2DAIA,uCAGA,wCACA,sDAGA,+CAGA,6DAEA,iDACA,+DAEA,wDAEA,sEAMA,0DACA,sBACA,mEL5JI,wEAEA,iCACE,+BAMN,wEAGA,iCACE,kFAEA,uEAIF,gEACE,8BAGF,qEMzDA,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,wFClFN,iCAGF,2DACE,4BACA,oCAKF,8BAGE,sCACA,+DAIA,sCAEA,sDAGA,gCACA,gEAGA,+CAEA,sBACE,yCAGF,uBACA,sEAIA,aAEA,mCAIA,kEACA,aACA,oEACA,YAIA,EAQE,4HAGA,gDACE,mBACA,wCAON,wCAGE,0DACA,mBAKA,mBACA,CANA,uCAKA,iBALA,iBAWA,mBAGF,mBACE,mDAIF,+BAEE,CAEA,yBAFA,kBAMA,CAJA,GACA,aAGA,mBAEF,wBAEE,iBACA,iBAEA,OACA,aAGF,CAHE,WAGF,GAEE,oBAEA,CAJF,gBAIE,aAEA,+CAKA,UANA,WACA,cADA,SAMA,WACA,iBAEE,GAMF,wBANE,yBAMF,kDACA,WAEA,gCACA,2DAGA,iBACE,uCAEJ,kEAIE,uCAGA,yDACE,cACA,+DAEA,yDAEE,mEAMJ,kEAMA,uBACA,kBAEA,uBACA,kDAKA,0DAIA,CALA,oBAKA,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,cCxaJ,iBAEE,aADA,iBACA,6BAEA,kCAEA,SACA,UAIA,gCACA,CALA,SAEA,SAEA,CAJA,wEAEA,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,yDCvEA,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,4DAMJ,mCACE,4BAGA,oBAGF,4CACE,qCACA,8BACA,gBACA,+CAEA,iCAEF,iCACE,oBACA,4CACA,qCAGF,8BAEE,+BAEA,WAEA,8BACE,oBACA,CADA,gBACA,yBAKF,gBADF,YACE,CACA,iBACA,qDAEA,mDCvIJ,2FAMA,iCACE,CACA,eAEA,CAFA,mBADA,wBAIA,8BACA,gBADA,YACA,0BAEE,8CAGA,wDAIE,gFAGE,iBAEN,wCAKF,+CACE,CACA,oDAEF,kDAIE,YAEF,CAHE,YAGF,CCpCE,mFAFA,QACA,UAIA,CAHA,IAGA,gDAGE,eACA,iEAGF,wBAEE,mBAMA,6CAEF,CAJE,mBACA,CAGF,kCAGE,CARF,kBACE,CAHA,eAUA,YACA,mBACA,CAFA,UAEA,wCC/BJ,mBACE,CDkCE,wBACA,sBCpCJ,iBACE,mDACA,2CACA,sBAGA,qBCDA,6CAIE,CATJ,uBAKE,CDGE,oBACF,yDAEE,CCDE,2CAGF,CAJA,kCACE,CDJJ,aAKE,eCXJ,CDME,uBCOE,gCACE,YAEF,2CAEE,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,oBCtCJ,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,6DCjFA,kDACA,gCACA,qDAGA,qBACA,qDCDA,cACA,eAEA,yBAGF,sBAEE,iBACA,sNAWA,iBACE,kBACA,wRAgBA,kBAEA,iOAgBA,uCACE,uEAEA,kBAEF,qUAuBE,iDAIJ,CACA,geCzFF,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/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\n@use \"../variables\" as *\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:\n -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif,\n Apple Color Emoji, Segoe UI Emoji;\n --font-stack--monospace:\n \"SFMono-Regular\", Menlo, Consolas, Monaco, Liberation Mono, Lucida Console,\n 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 *\n #{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","@use \"sass:list\";\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}: #{list.nth($values, 1)};\n --color-admonition-title-background--#{$name}: #{rgba(\n list.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@use \"variables\" as *\n\nhtml\n overflow-x: hidden\n overflow-y: scroll\n scroll-behavior: smooth\n\n.sidebar-scroll, .toc-scroll, article[role=main] *\n scrollbar-width: thin\n scrollbar-color: var(--color-foreground-border) transparent\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","@use \"sass:list\"\n@use \"../variables\" as *\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-#{list.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 > .highlight\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","@use \"../variables\" as *\n\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@use \"../variables\" as *\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