Feature/135 is smaller region

.gitignore

@@ -161,3 +161,5 @@ examples/demo2d/**/results
 # Cmake generated files
 CMakeUserPresets.json
 
+# Claude Code
+.claude/

.vscode/settings.json

@@ -49,4 +49,7 @@
     "mypy-type-checker.reportingScope": "workspace",
     "mypy-type-checker.preferDaemon": true,
     "ruff.configurationPreference": "filesystemFirst",
+    "cSpell.words": [
+        "effecient"
+    ],
 }

CLAUDE..md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**axtreme** is a Python library extending Ax (Facebook's Adaptive Experimentation) and BoTorch (Bayesian Optimization in PyTorch) for design of experiments, active learning, and extreme response analysis. It targets reliability engineering scenarios like estimating 50-year storm loads from surrogate models.
+
+## Build & Development Commands
+
+```bash
+uv sync                              # Install all dependencies (dev included)
+uv sync --extra cuda                 # With CUDA support
+uv sync --extra examples             # With example dependencies (openturns, numba)
+uv run pre-commit install            # Setup pre-commit hooks
+
+# Testing
+uv run pytest                        # Run all tests
+uv run pytest tests/path/test_file.py::test_name  # Single test
+uv run pytest -m "not system"        # Skip long-running system tests
+uv run pytest --cov                  # With coverage
+
+# Linting & Formatting
+uv run ruff format                   # Format code
+uv run ruff check --fix              # Lint with auto-fix
+uv run pyright                       # Type checking (primary)
+uv run mypy                          # Type checking (secondary)
+uv run pre-commit run --all-files    # Run all checks (ruff, pyright, mypy)
+```
+
+## Architecture
+
+### Core Protocols (structural subtyping via `typing.Protocol`)
+
+The codebase is designed around three key protocols that define the extension points:
+
+- **`Simulator`** (`simulator/base.py`): `__call__(x: ndarray[n_points, n_dims], n_simulations_per_point) -> ndarray[n_points, n_sims, n_outputs]` -- wraps any simulation model.
+- **`QoIEstimator`** (`qoi/qoi_estimator.py`): `__call__(model: Model) -> Tensor[n_estimates]` -- estimates a scalar quantity of interest from a BoTorch surrogate model. Has `mean()` and `var()` methods for aggregation (overridable for special samplers like UT).
+- **`PosteriorSampler`** (`sampling/base.py`): `__call__(posterior: GPyTorchPosterior) -> Tensor` -- draws samples from GP posteriors with different strategies.
+
+### Bayesian Optimization Loop (how modules connect)
+
+1. **Experiment setup** (`experiment.py`): Create Ax Experiment, initialize with Sobol points
+2. **Simulation** (`evaluation.py`): `EvaluationFunction` wraps a `Simulator`, runs it, fits a distribution (Gumbel) to outputs -> `SimulationPointResults`
+3. **Ax integration** (`runner.py` + `metrics.py`): `LocalMetadataRunner` executes evaluation, stores results in trial metadata; `LocalMetadataMetric` fetches them back
+4. **Surrogate model**: Ax/BoTorch fits a GP to collected data
+5. **QoI estimation** (`qoi/`): Either `GPBruteForce` (full-period simulation) or `MarginalCDFExtrapolation` (CDF^N extrapolation) estimates the extreme response quantity
+6. **Acquisition** (`acquisition/qoi_look_ahead.py`): `QoILookAhead` uses fantasy models to select the next point that most reduces QoI variance
+7. Repeat from step 2
+
+### Key Module Purposes
+
+- **`qoi/`**: Two strategies for extreme value estimation. `GPBruteForce` simulates all timesteps per period. `MarginalCDFExtrapolation` approximates via single-timestep CDF raised to power N -- much faster for large N.
+- **`sampling/`**: `MeanSampler` (no uncertainty), `IndependentMCSampler` (diagonalizes cross-point covariance), `NormalIndependentSampler`, `UTSampler` (unscented transform, needs custom mean/var).
+- **`distributions/`**: `ApproximateMixture` (conservative tail extrapolation for safety-critical use), `icdf` (inverse CDF via root-finding for distributions without analytic inverse).
+- **`data/`**: PyTorch Dataset/Sampler wrappers including `NumpyFileDataset` (memory-mapped), importance sampling support, custom batch samplers.
+- **`utils/transforms.py`**: Converts Ax transforms to BoTorch space so models can operate in problem space rather than Ax's normalized space.
+- **`eval/`**: `QoIJob`/`QoIJobResult` for organizing and serializing QoI evaluation runs.
+
+### Tensor Dimension Conventions (BoTorch notation)
+
+- `*b`: batch dimensions (arbitrary)
+- `n`: number of input points
+- `m`: output dimensionality
+- GP posterior shape: `(*b, n, m)`
+
+## Code Style
+
+- **Formatter/Linter**: Ruff (configured in `ruff.toml`). Selects ALL rules then ignores specific ones.
+- **Line length**: 120 characters
+- **Docstrings**: Follow Google style.
+- **Type hints**: Required on all functions. Pyright in basic mode with strict-ish overrides. Stubs in `stubs/` directory for untyped third-party libraries.
+- **Imports**: Absolute only (no relative imports). Grouped: stdlib, third-party, local.
+- **Test markers**: `integration`, `external`, `system` (very long), `non_deterministic`. Tests mirror `src/` structure.
+- **TODOs**: Use `# @TODO: Description. AUTHOR, YYYY-MM-DD` format.
+
+## Important Constraints
+
+- **numpy < 2.0**: Pinned for compatibility with the scipy/torch/botorch ecosystem.
+- **ax-platform == 0.3.7**: Pinned exact version; Ax APIs can change significantly between versions.
+- **Single output only**: Multi-output GP support is not yet implemented across the QoI pipeline.

STYLEGUIDE.md

@@ -305,31 +305,27 @@ If you are interested in the long story including the why‘s, read these discus
 
 ## Docstrings
 
-* All Docstrings should be written in [Numpy](https://numpydoc.readthedocs.io/en/latest/format.html) format. For a good tutorial on Docstrings, see [Documenting Python Code: A Complete Guide](https://realpython.com/documenting-python-code)
+* All Docstrings should be written in [Google](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) format. For a good tutorial on Docstrings, see [Documenting Python Code: A Complete Guide](https://realpython.com/documenting-python-code)
 * In a Docstring, summarize function/method behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions
 * Wrap Docstrings with triple double quotes (""")
 * The description of the arguments must be indented
 
 ```py
-    def some_method(name, print=False):
-        """This function does something
-
-        Parameters
-        ----------
-        name : str
-            The name to use
-        print: bool, optional
-            A flag used to print the name to the console, by default False
-
-        Raises
-        ------
-        KeyError
-            If name is not found
-
-        Returns
-        -------
-        int
-            The return code
+    def some_method(name: str, print: bool = False):
+        """Short description of some_method's purpose.
+
+        More in depth description of some_method's behavior, side effects, etc.
+
+        Args:
+            name: description of the arguments purpose. Only provide type info not in signature.
+            print: Some long description that might need to be wrapped to multiple lines. This
+              is done using an indent.
+
+        Returns:
+            Semantic description of the return value
+
+        Raises:
+            IOError: What condition this error might be raised.
         """
         ...
         return 0