### Set up development environment

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/installation.md

Clone the repository, create a virtual environment, and install extended requirements for development, benchmarking, or examples.

```bash
# Clone the repository
git clone https://github.com/ndeutschmann/zunis.git ./zunis
# Create a virtual environment (recommended)
python3.8 -m venv  zunis_venv
source ./zunis_venv/bin/activate
pip install --upgrade pip
# Install the requirements
cd ./zunis
pip install -r requirements.txt
# Run one benchmark (GPU highly recommended)
cd ./experiments/benchmarks
python benchmark_hypersphere.py
```

--------------------------------

### Set up Development Environment

Source: https://github.com/ndeutschmann/zunis/blob/master/README.md

Clone the repository, create a virtual environment, and install development requirements for contributing or running examples.

```bash
# Clone the repository
git clone https://github.com/ndeutschmann/zunis.git ./zunis
# Create a virtual environment (recommended)
python3.7 -m venv  zunis_venv
source ./zunis_venv/bin/activate
pip install --upgrade pip
# Install the requirements
cd ./zunis
pip install -r requirements.txt
# Run one benchmark (GPU recommended)
cd ./experiments/benchmarks
python benchmark_hypersphere.py
```

--------------------------------

### Install ZüNIS using pip

Source: https://github.com/ndeutschmann/zunis/blob/master/README.md

Install the ZüNIS library from PyPI using pip.

```bash
pip install zunis
```

--------------------------------

### Install ZüNIS from GitHub

Source: https://github.com/ndeutschmann/zunis/blob/master/README.md

Install the latest version of ZüNIS directly from its GitHub repository.

```bash
pip install 'git+https://github.com/ndeutschmann/zunis#egg=zunis&subdirectory=zunis_lib'
```

--------------------------------

### Import Libraries and Setup

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmarks_02/2021.03.09.exploration.ipynb

Imports necessary libraries for data manipulation, database interaction, and plotting. Sets up seaborn for enhanced visualizations.

```python
import pandas as pd
import sqlite3 as sql
import seaborn as sns
import matplotlib.pyplot as plt
import numpy as np
from matplotlib import ticker as mticker
from sqlalchemy import PickleType

sys.path.append("../")
from utils.data_storage.dataframe2sql import read_pkl_sql
from utils.config.loaders import get_sql_types


sns.set_theme()
sns.set(font_scale=1.2)
sns.set_style("whitegrid")
```

--------------------------------

### Import Libraries and Setup

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmarks_01/02.best_perf.ipynb

Imports necessary libraries for data manipulation, analysis, and visualization. Sets up seaborn for enhanced plotting aesthetics.

```python
import pandas as pd
import sqlite3 as sql
import seaborn as sns
import matplotlib.pyplot as plt
import numpy as np
from matplotlib import ticker as mticker
from sqlalchemy import PickleType

import sys
sys.path.append("../")
from utils.data_storage.dataframe2sql import read_pkl_sql
from utils.config.loaders import get_sql_types


sns.set_theme()
sns.set(font_scale=1.2)
sns.set_style("whitegrid")
```

--------------------------------

### Setup Plotting Environment

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmark_madgraph/benchmark_01/madgraph_benchmarks_figures.ipynb

Configures Matplotlib and Seaborn for plotting, setting font sizes, LaTeX rendering, and plot dimensions. Includes theme and style settings for Seaborn.

```python
import numpy as np
import pandas as pd
import pickle
import seaborn as sns
import matplotlib.pyplot as plt
import math
from num2tex import num2tex



plt.rcParams.update({
    'font.size': 8,
    'text.usetex': True,
    'text.latex.preamble': r'\usepackage{amsfonts}',
    "figure.figsize": (6,4),
    'figure.dpi':150
})

sns.set_theme()
sns.set(font_scale=1.3)
sns.set_style("whitegrid")
```

--------------------------------

### Instantiate and Use Custom Coupling Cell for Training

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/_sources/library/tutorial/coupling.rst.txt

Instantiate a custom coupling cell and integrate it into the `StatefulTrainer`. This example uses a `FactorizedGaussianSampler` as the flow prior.

```python
import torch
from zunis.models.flows.sampling import FactorizedGaussianSampler
from zunis.training.weighted_dataset.stateful_trainer import StatefulTrainer

d = 2
device = torch.device("cpu")

mask=[True,False]
nn_width=8
nn_depth=256

sampler=FactorizedGaussianSampler(d=d)
linear_coupling=LinearCouplingCell(d,mask,nn_width,nn_depth)
trainer = StatefulTrainer(d=d, loss="variance", flow_prior=sampler,flow=linear_coupling, device=device)
```

--------------------------------

### Instantiate and Train with Custom Coupling Cell

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/tutorial/coupling.md

Instantiate the custom `LinearCouplingCell` and integrate it into the `StatefulTrainer`. This example sets up the necessary components like the sampler, dimensions, and neural network parameters.

```python
d = 2
device = torch.device("cpu")

mask=[True,False]
nn_width=8
nn_depth=256

sampler=FactorizedGaussianSampler(d=d)
linear_coupling=LinearCouplingCell(d,mask,nn_width,nn_depth)
trainer = StatefulTrainer(d=d, loss="variance", flow_prior=sampler,flow=linear_coupling, device=device)
```

--------------------------------

### Get Current Working Directory

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmarks_02/2021.03.09.exploration.ipynb

Prints the current working directory.

```python
pwd
```

--------------------------------

### Load Data and Configure SQL Types

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmarks_03/01.camel_default_benchmarks_figures.ipynb

Imports functions for reading data from SQL databases and getting SQL type mappings. Establishes a connection to the 'benchmarks.db' SQLite database.

```python
from utils.data_storage.dataframe2sql import read_pkl_sql
from utils.config.loaders import get_sql_types
import sqlite3 as sql
from sqlalchemy import PickleType
```

```python
con = sql.connect("benchmarks.db")
con.cursor().execute("SELECT name FROM sqlite_master where type = 'table'").fetchall()
```

--------------------------------

### Invert Normalizing Flow Example

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/tutorial/invert.md

Demonstrates training a normalizing flow and then inverting it to restore original samples. Call `.invert()` on the flow to switch from forward to backward operation.

```python
import torch
from zunis.models.flows.sampling import UniformSampler
from zunis.training.weighted_dataset.stateful_trainer import StatefulTrainer

device = torch.device("cpu")

d = 2

def f(x):
  return x[:,0]**2 + x[:,1]**2

trainer = StatefulTrainer(d=d, loss="variance", flow="pwquad", device=device)

n_points = 3
# Uniformly sampled points
x = torch.rand(n_points,d,device=device)
print(x) #[[0.8797, 0.0277],[0.4615, 0.8289],[0.7171, 0.5085]]

px = torch.ones(n_points)
# px.shape = (n_points,)

# Function values
fx = f(x)

sample = x, px, fx
trainer.train_on_batch(x,px,fx)

y=trainer.flow(torch.cat((x,px.unsqueeze(-1)),-1))
print(y[:,:-1]) #[[0.8903, 0.0952],[0.2285, 0.6719],[0.5979, 0.3470]]

trainer.flow.invert()
q=trainer.flow(y)
print(q[:,:-1]) #[[0.8797, 0.0277],[0.4615, 0.8289], [0.7171, 0.5085]]
```

--------------------------------

### TrainingRecord Methods

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Methods for managing training records, including starting a new epoch and advancing to the next step.

```APIDOC
## TrainingRecord.new_epoch()

### Description
Starts a new epoch for the training record.

### Method
TrainingRecord.new_epoch()

### Endpoint
N/A (Method within a class)

### Parameters
None

### Request Example
None

### Response
None
```

```APIDOC
## TrainingRecord.next_step()

### Description
Advances the training record to the next step.

### Method
TrainingRecord.next_step()

### Endpoint
N/A (Method within a class)

### Parameters
None

### Request Example
None

### Response
None
```

--------------------------------

### Import Libraries for Benchmarking

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmarks_04/01.camel_default_benchmarks_figures.ipynb

Imports essential Python libraries for data manipulation, plotting, and Zunis integration configuration. Ensure these libraries are installed.

```python
from pathlib import Path
import sys
import seaborn as sns
import matplotlib.pyplot as plt
import pandas as pd
import numpy as np
import matplotlib
import torch

from zunis.utils.config.loaders import get_default_integrator_config
from zunis.utils.config.loaders import create_integrator_args
from utils.integrands.camel import KnownSymmetricCamelIntegrand
from pprint import pprint
```

--------------------------------

### Minimal Integrator Usage in ZüNIS

Source: https://context7.com/ndeutschmann/zunis/llms.txt

Demonstrates the basic setup and usage of the ZüNIS Integrator with default parameters. Ensure torch is available and the integrand function accepts and returns tensors of the correct shape.

```python
import torch
from zunis.integration import Integrator
import zunis

# Enable logging output
zunis.setup_std_stream_logger()

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
d = 4

# Integrand: f must accept torch.Tensor of shape (N, d) and return shape (N,)
def f(x):
    # Integrate sum of squares over [0,1]^4 — exact answer = 4/3
    return x.pow(2).sum(axis=1)

# Minimal usage: all defaults
integrator = Integrator(f=f, d=d, device=device)
result, uncertainty, history = integrator.integrate()
print(f"Result: {result:.5e} +/- {uncertainty:.3e}")
# Result: 1.33350e+00 +/- 2.1e-04
```

--------------------------------

### Typical Configuration Logging Process

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/benchmarks_api/utils.config.md

Demonstrates the standard workflow for configuring and logging integrator settings. This involves obtaining default configurations, customizing them, preparing arguments, and finally logging the flattened configuration.

```python
config = get_default_integrator_config()
# ... override some config details
args = create_integrator_args(config)
Integrator(..., **args)
flat_config = config.to_dict_flat()
# ... log the flat config somewhere
```

--------------------------------

### Create and Load Integrator with Custom Configuration

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/_sources/library/tutorial/config.rst.txt

Shows how to generate a new configuration file based on an existing one, modifying specific parameters like `n_points_survey`, and then load the Integrator using this new configuration.

```python
import torch
from zunis.integration import Integrator
from zunis.utils.config.loaders import create_integrator_args
from zunis.utils.config.generators import create_integrator_config_file

device = torch.device("cpu")

d = 2

def f(x):
    return x[:,0]**2 + x[:,1]**2

create_integrator_config_file(filepath="integrator_config_new.yaml", base_config="integrator_config_old.yaml", n_points_survey=20000)
integrator = Integrator(f,d,**create_integrator_args("integrator_config_new.yaml"),device=device)
result, uncertainty, history = integrator.integrate()
```

--------------------------------

### Get Default Integrator Arguments

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/library/integrator.html

Call `create_integrator_args` without arguments to get a keyword dictionary with default integrator options. This is useful for inspecting default settings.

```python
from zunis.utils.config.loaders import create_integrator_args

kwargs = create_integrator_args()
integrator = integrator(d=2, f=f, **kwargs)
print(kwargs)
```

--------------------------------

### Load Integrator with Default Configuration

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/_sources/library/tutorial/config.rst.txt

Demonstrates how to load the Integrator using default arguments, which includes loading a configuration from a default YAML file if no path is provided.

```python
import torch
from zunis.integration import Integrator
from zunis.utils.config.loaders import create_integrator_args

device = torch.device("cpu")

d = 2

def f(x):
    return x[:,0]**2 + x[:,1]**2

integrator = Integrator(f,d,**create_integrator_args(),device=device)
result, uncertainty, history = integrator.integrate()
```

--------------------------------

### Sample Forward Pass and Flow Inversion with StatefulTrainer

Source: https://context7.com/ndeutschmann/zunis/llms.txt

Demonstrates how to perform a forward pass to map data to the learned space and invert the flow to reconstruct original data. Also shows saving and loading model weights for sampling.

```python
import torch
from zunis.models.flows.sampling import UniformSampler
from zunis.training.weighted_dataset.stateful_trainer import StatefulTrainer

device = torch.device("cpu")
d = 2

def f(x):
    return x[:, 0] ** 2 + x[:, 1] ** 2

trainer = StatefulTrainer(d=d, loss="variance", flow="pwquad", device=device)

# Train on a small batch
n = 3
x = torch.rand(n, d, device=device)
px = torch.ones(n, device=device)
fx = f(x)
trainer.train_on_batch(x, px, fx)

# Forward pass: map x → y (learned space), get jacobian
xj = torch.cat((x, px.unsqueeze(-1)), -1)
y = trainer.flow(xj)           # shape (n, d+1): y[:,:-1] = mapped coords, y[:,-1] = log-jac
print("Mapped points:", y[:, :-1])

# Invert the flow: map y → x (reconstructed)
trainer.flow.invert()          # toggle flow direction
x_reconstructed = trainer.flow(y)
print("Reconstructed:", x_reconstructed[:, :-1])
# Should match original x

# Toggle back to forward mode for sampling
trainer.flow.invert()

# Save and reload model weights
torch.save(trainer.flow.state_dict(), "flow_weights.pt")

trainer2 = StatefulTrainer(d=d, loss="variance", flow="pwquad", device=device)
trainer2.flow.load_state_dict(torch.load("flow_weights.pt"))
samples = trainer2.sample_forward(1000)   # shape (1000, d+1)
print(f"Loaded model samples shape: {samples.shape}")
```

--------------------------------

### Get SQL Data Types

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/notebooks/2021.08.30.pretty_2d_plots.ipynb

Fetches the SQL data types configuration.

```python
dtypes = get_sql_types()
```

--------------------------------

### Loading Configuration with create_integrator_args

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/tutorial/config.md

This Python snippet demonstrates how to load a configuration file using `create_integrator_args`. If `None` is passed, the default `integrator_config.yaml` is used.

```python
import torch
from zunis.integration import Integrator
from zunis.utils.config.loaders import create_integrator_args

device = torch.device("cpu")

d = 2

def f(x):
    return x[:,0]**2 + x[:,1]**2

integrator = Integrator(f,d,**create_integrator_args(),device=device)
result, uncertainty, history = integrator.integrate()

```

--------------------------------

### Get Default Integrator Configuration

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/notebooks/2021.08.30.pretty_2d_plots.ipynb

Retrieves the default configuration settings for the integrator.

```python
get_default_integrator_config()
```

--------------------------------

### generate_target_batch_from_posterior

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/api/zunis.training.weighted_dataset.weighted_dataset_trainer.html

Generates a batch of training examples in the target space by sampling from a specified distribution.

```APIDOC
## generate_target_batch_from_posterior(n_points, f, target_posterior)

### Description
Generate a batch of training examples in target space from a specified distribution.

### Parameters
#### Path Parameters
- **n_points** - Required - size of the batch
- **f** - Required - function to evaluate on the sampled points
- **target_posterior** - Required - distribution from which to sample points in target_space

### Returns
(x,px,fx): sampled points, sampling distribution PDF values, function values

### Return Type
tuple of torch.Tensor
```

--------------------------------

### get_pipfreeze_hash

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/benchmarks_api/utils.repo_info.html

Computes a hash based on the output of 'pip freeze', representing the installed libraries in the current environment.

```APIDOC
## get_pipfreeze_hash

### Description
Get a hash of the libraries installed in the current environment - generated by pip freeze

### Returns
- **str** - A hash of the installed libraries.
```

--------------------------------

### Train on Pickle File Sample

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/library/tutorial/preeval.html

Import a pre-evaluated sample directly from a pickle file. The pickle file must contain a 3-tuple of PyTorch tensors (points, pdf values, function values) on the same device.

```python
import torch
import pickle
from zunis.integration import Integrator

device = torch.device("cuda")

d = 2

def f(x):
  return x[:,0]**2 + x[:,1]**2

integrator =  Integrator(d=d, f=f, survey_strategy='fixed_sample', device=device, n_points_survey=1000)

data_x = torch.rand(1000,d,device=device)
#[[0.2093, 0.9918],[0.3216, 0.6965],[0.0625, 0.5634],...]
data_px = torch.ones(1000)
# [1.0,1.0,1.0...]

sample=(data_x.clone().detach(),data_px.clone().detach(),f(data_x.clone().detach()))
pickle.dump(sample, open("sample.p","wb"))

integrator.set_sample_pickle("sample.p",device=device)
result, uncertainty, history = integrator.integrate()
```

--------------------------------

### Get Unique Values of 's'

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmarks_01/01.first_exploration.ipynb

Retrieves and displays the unique values present in the 's' column of the DataFrame.

```python
df["s"].unique()
```

--------------------------------

### Compute Integral and Get Results

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/_sources/library/integrator.rst.txt

Call the integrate method on an instantiated integrator to compute the integral, obtaining the result, uncertainty, and history.

```python
result, uncertainty, history = integrator.integrate()
print(f"{result:.3e} +/- {uncertainty:.3}")
# > 6.666e-01 +/- 4.69e-05
```

--------------------------------

### zunis.setup_std_stream_logger

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Sets up a standard stream logger for the Zunis library.

```APIDOC
## zunis.setup_std_stream_logger

### Description
Initializes and configures a standard stream logger for use with the Zunis library.

### Method
(Not specified in source, likely a Python function call)

### Endpoint
(Not applicable, this is an SDK function)

### Parameters
(Parameters not specified in source)

### Request Example
(Not applicable)

### Response
(Response details not specified in source)
```

--------------------------------

### Define a Custom Invertible Transform

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/_sources/library/tutorial/coupling.rst.txt

Define a custom invertible transform by inheriting from `InvertibleTransform`. This example shows a simple linear mapping.

```python
import torch
from zunis.models.flows.coupling_cells.general_coupling import InvertibleCouplingCell
from zunis.models.flows.coupling_cells.transforms import InvertibleTransform
from zunis.models.layers.trainable import ArbitraryShapeRectangularDNN

class LinearTransform(InvertibleTransform):
    def forward(self,x,T):
        alpha = torch.exp(T)
        logj = T*x.shape[-1]
        return x*alpha, logj.squeeze()
    def backward(self,x,T):
        alpha = torch.exp(-T)
        logj = -T*x.shape[-1]
        return x*alpha, logj.squeeze()
```

--------------------------------

### Run Benchmark with Modified Configuration

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/notebooks/2021.08.30.pretty_2d_plots.ipynb

Creates a copy of the base configuration and modifies parameters such as epochs, bins, masking, and learning rate before running the benchmark using `sw_pretty_plot`. Logs output to a file.

```python
config = deepcopy(base_config)
config["n_epochs"] = 5
config["n_bins"] = 20
config['masking']='iflow'
config["repetitions"] = 2
config['d_hidden'] = 128
config["lr"] = 1.e-4
config['loss'] = 'variance'
result, integrator = sw_pretty_plot(config)
```

--------------------------------

### initialize

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/api/zunis.integration.base_integrator.html

Initializes the integrator before the whole integration process begins.

```APIDOC
initialize(**kwargs)
    """Intialization before the whole integration process"""
```

--------------------------------

### Configure Logging with zunis.setup_std_stream_logger

Source: https://context7.com/ndeutschmann/zunis/llms.txt

Call setup_std_stream_logger to route INFO-level messages to stdout and WARNING+ to stderr. Set debug=True to enable debug-level output.

```python
import torch
import zunis
from zunis.integration import Integrator

# Route INFO → stdout, WARNING+ → stderr
zunis.setup_std_stream_logger(min_level=None, debug=False)

# Enable debug-level output
zunis.setup_std_stream_logger(debug=True)

d = 2
def f(x):
    return x[:, 0] ** 2 + x[:, 1] ** 2

integrator = Integrator(f=f, d=d, device=torch.device("cpu"), verbosity=2)
result, uncertainty, history = integrator.integrate()
# stdout will now show per-step integral estimates:
# INFO: Integral: 6.667e-01 +/- 4.5e-04
# INFO: Final result: 6.6667e-01 +/- 2.31e-04
```

--------------------------------

### Loading Integrator Configuration with create_integrator_args

Source: https://context7.com/ndeutschmann/zunis/llms.txt

Illustrates how to load and resolve a YAML configuration file into keyword arguments suitable for the `Integrator` factory using `create_integrator_args`. This function handles default loading and argument resolution, including optimizer instantiation.

```python
import torch
from zunis.integration import Integrator
from zunis.utils.config.loaders import create_integrator_args, get_default_integrator_config

device = torch.device("cpu")
d = 3

def f(x):
    return x[:, 0] * x[:, 1] + x[:, 2] ** 2

# Load defaults and inspect them
kwargs = create_integrator_args()
print(kwargs)
# {'flow': 'pwquad',
#  'flow_options': {'cell_params': {'d_hidden': 256, 'n_bins': 10, 'n_hidden': 8},
#                   'masking': 'iflow', 'masking_options': {'repetitions': 2}},
#  'loss': 'variance', 'n_iter': 10, 'n_points_survey': 10000,
#  'trainer_options': {'checkpoint': True, 'n_epochs': 50, ...}}
```

--------------------------------

### Connect to Database and Query Tables

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmarks_04/01.camel_default_benchmarks_figures.ipynb

Establishes a connection to the 'benchmarks.db' SQLite database and queries for existing table names. This helps in identifying available datasets.

```python
con = sql.connect("benchmarks.db")
con.cursor().execute("SELECT name FROM sqlite_master where type = 'table'").fetchall()
```

--------------------------------

### Basic Integrator Usage

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/basic-example.md

Use this snippet for the most basic integration tasks. Ensure torch is installed and the function `f` adheres to the specified input/output tensor shapes and device.

```python
import torch
from zunis.integration import Integrator

device = torch.device("cuda")

d = 2

def f(x):
    return x[:,0]**2 + x[:,1]**2

integrator = Integrator(d=d,f=f,device=device)
result, uncertainty, history = integrator.integrate()
```

--------------------------------

### Train with Pickle File Sample

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/tutorial/preeval.md

Import pre-evaluated samples directly from a pickle file. The file must contain a batch of data structured as a 3-tuple of PyTorch tensors (points, pdf values, function values).

```python
import torch
import pickle
from zunis.integration import Integrator

device = torch.device("cuda")

d = 2

def f(x):
  return x[:,0]**2 + x[:,1]**2

integrator =  Integrator(d=d, f=f, survey_strategy='fixed_sample', device=device, n_points_survey=1000)

data_x = torch.rand(1000,d,device=device)
#[[0.2093, 0.9918],[0.3216, 0.6965],[0.0625, 0.5634],...]
data_px = torch.ones(1000)
#[1.0,1.0,1.0...]

sample=(data_x.clone().detach(),data_px.clone().detach(),f(data_x.clone().detach()))
pickle.dump(sample, open("sample.p","wb"))

integrator.set_sample_pickle("sample.p",device=device)
result, uncertainty, history = integrator.integrate()
```

--------------------------------

### BasicStatefulTrainer.set_config()

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Sets the configuration for the stateful trainer.

```APIDOC
## BasicStatefulTrainer.set_config()

### Description
Sets the configuration for the stateful trainer.

### Method
(Method signature from source)

### Parameters
(No parameters explicitly documented)

### Response
(No response details explicitly documented)
```

--------------------------------

### Sampler.sample()

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Generic sampling method.

```APIDOC
## Sampler.sample()

### Description
Generic sampling method.

### Method
(Method signature from source)

### Parameters
(No parameters explicitly documented)

### Response
(No response details explicitly documented)
```

--------------------------------

### GridBenchmarker.generate_config_samples

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/benchmarks_api/utils.benchmark.benchmarker.html

Samples configurations by iterating through dimensions, integrator options, and integrand options in a grid-like fashion.

```APIDOC
## GridBenchmarker.generate_config_samples

Sample over dimensions, integrator and integrand configurations from lists of possible option values.

Parameters:

*   **dimensions** (_List[int]_) – list of dimensions to sample from
*   **integrator_grid** (_Dict[str, List[Any]]_) – mapping (option name) -> (list of values) for the integrator
*   **integrand_grid** (_Dict[str, List[Any]]_) – mapping (option name) -> (list of values) for the integrand

Yields:

*   _Tuple[int, Dict[str, Any], Dict[str, Any]]_ – triplets (d, integrator_config, integrand_params) that can be used to sample configurations
```

--------------------------------

### Train with CSV File Sample

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/tutorial/preeval.md

Import pre-evaluated samples from a CSV file. The CSV must have d+2 columns: the first d for points, the next for sampling distribution PDF values, and the last for function values. Specify device and dtype for import.

```python
import torch
import numpy as np
from zunis.integration import  Integrator

device = torch.device("cuda")

d = 2

integrator =  Integrator(d=d, f=f, survey_strategy='fixed_sample', device=device, n_points_survey=1000)

integrator.set_sample_csv("sample.csv",device="cuda",dtype=np.float32)
result, uncertainty, history = integrator.integrate()
```

--------------------------------

### Define a Custom Invertible Transform

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/tutorial/coupling.md

Implement an invertible transform by inheriting from `InvertibleTransform`. This example defines a simple linear transformation with its forward and backward passes, including the log-determinant of the Jacobian.

```python
import torch
from zunis.models.flows.sampling import FactorizedGaussianSampler
from zunis.training.weighted_dataset.stateful_trainer import StatefulTrainer
from zunis.models.flows.coupling_cells.general_coupling import InvertibleCouplingCell
from zunis.models.flows.coupling_cells.transforms import InvertibleTransform
from zunis.models.layers.trainable import ArbitraryShapeRectangularDNN

class LinearTransform(InvertibleTransform):
  def forward(self,x,T):
      alpha = torch.exp(T)
      logj = T*x.shape[-1]
      return x*alpha, logj.squeeze()
  def backward(self,x,T):
      alpha = torch.exp(-T)
      logj = -T*x.shape[-1]
      return x*alpha, logj.squeeze()
```

--------------------------------

### Generating and Loading a New Configuration File

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/tutorial/config.md

This Python snippet shows how to generate a new configuration file based on an existing one, modify parameters, and then load it for the Integrator. It uses `create_integrator_config_file` to generate the new file.

```python
import torch
from zunis.integration import Integrator
from zunis.utils.config.loaders import create_integrator_args
from zunis.utils.config.generators import create_integrator_config_file

device = torch.device("cpu")

d = 2

def f(x):
    return x[:,0]**2 + x[:,1]**2

create_integrator_config_file(filepath="integrator_config_new.yaml", base_config="integrator_config_old.yaml", n_points_survey=20000)
integrator = Integrator(f,d,**create_integrator_args("integrator_config_new.yaml"),device=device)
result, uncertainty, history = integrator.integrate()

```

--------------------------------

### Generate Config Files with create_integrator_config_file

Source: https://context7.com/ndeutschmann/zunis/llms.txt

Create or update integrator configuration files using YAML. This function allows starting from defaults, basing on existing configs, and overriding parameters. It's useful for reproducible experiment tracking.

```python
from zunis.utils.config.generators import create_integrator_config_file
from zunis.utils.config.loaders import create_integrator_args
from zunis.integration import Integrator
import torch

device = torch.device("cpu")
d = 2

def f(x):
    return x[:, 0] ** 2 + x[:, 1] ** 2

# Create a new config file from defaults, overriding specific parameters
create_integrator_config_file(
    filepath="my_integrator_config.yaml",
    base_config=None,        # None = start from built-in defaults
    force=True,              # overwrite if exists
    n_points_survey=20000,
    n_iter=15,
)

# Load the saved config and use it
integrator = Integrator(
    f=f, d=d,
    device=device,
    **create_integrator_args("my_integrator_config.yaml")
)
result, uncertainty, history = integrator.integrate()
print(f"Result: {result:.4e} +/- {uncertainty:.3e}")

# Chain: load old config, modify, save as new config
create_integrator_config_file(
    filepath="refined_config.yaml",
    base_config="my_integrator_config.yaml",
    n_points_survey=50000,
    n_iter=30,
)
```

--------------------------------

### Instantiate and Integrate with Integrator

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/integrator.md

Instantiate the Integrator with specified iteration counts for survey and refine phases. Override the number of survey and refine samples at integration time.

```python
integrator = Integrator(d=d, f=f, n_iter_survey=3, n_iter_refine=5) # Default values
integrator.integrate(n_survey=10, n_refine=10) # Override at integration time
```

--------------------------------

### Gaussian Integral in R^d using ZüNIS

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/tutorial/Rd.md

This snippet shows how to set up and perform integration over R^d. It defines the target function, applies a variable transformation (tan) to map [0,1] to R, and then uses the ZüNIS Integrator. Ensure torch and numpy are installed.

```python
import torch
import numpy as np
from zunis.integration import Integrator

device = torch.device("cuda")

d = 2

def f(x):
    return torch.exp(-(x).square().sum(axis=1))

def f_wrapped(x):
    return f(torch.tan(np.pi*(x-0.5)))*((np.pi/(torch.cos(np.pi*(x-0.5)).square()))).prod(axis=1)

integrator = Integrator(d=d,f=f_wrapped,device=device)
result, uncertainty, history = integrator.integrate()
```

--------------------------------

### Define Integration Parameters

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/notebooks/2021.08.30.pretty_2d_plots.ipynb

Sets up basic parameters for the integration, including dimensionality, scale, and normalization.

```python
d=2
s = 0.15
norm = 1
```

--------------------------------

### Create Integrator Arguments from Defaults

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/integrator.md

Generate a keyword dictionary with default options for an integrator using `create_integrator_args`. This dictionary can then be used to initialize an `Integrator`.

```python
from zunis.utils.config.loaders import create_integrator_args

kwargs = create_integrator_args()
integrator = integrator(d=2, f=f, **kwargs)
print(kwargs)
#{'flow': 'pwquad',
#'flow_options': {'cell_params': {'d_hidden': 256, 'n_bins': 10, 'n_hidden': 8},
#                  'masking': 'iflow',
#                 'masking_options': {'repetitions': 2}},
#'loss': 'variance',
#'n_iter': 10,
#'n_points_survey': 10000,
#'trainer_options': {'checkpoint': True,
#                    'checkpoint_on_cuda': True,
#                    'checkpoint_path': None,
#                    'max_reloads': 0,
#                    'minibatch_size': 1.0,
#                    'n_epochs': 50,
#                    'optim': <class 'torch.optim.adam.Adam'>}}
```

--------------------------------

### Gaussian Integral in R^2 using ZüNIS

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/_sources/library/tutorial/Rd.rst.txt

This code demonstrates how to compute a Gaussian integral in two dimensions using ZüNIS. It involves defining the target function and a wrapped version suitable for ZüNIS's integration domain, along with the necessary imports and integrator setup.

```python
import torch
import numpy as np
from zunis.integration import Integrator

device = torch.device("cuda")

d = 2

def f(x):
    return torch.exp(-(x).square().sum(axis=1))

def f_wrapped(x):
    return f(torch.tan(np.pi*(x-0.5)))*((np.pi/(torch.cos(np.pi*(x-0.5)).square()))).prod(axis=1)
    
integrator = Integrator(d=d,f=f_wrapped,device=device)
result, uncertainty, history = integrator.integrate()
```

--------------------------------

### Configure Base Integrator Settings

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/notebooks/2021.08.30.pretty_2d_plots.ipynb

Sets up a base configuration for the integrator, including dimensions, integrand parameters, and various training/sampling settings. This configuration is used as a template for experiments.

```python
base_config = Configuration({
    "dimensions": d,
    "base_integrand_params": {
        "f":f,
        "offset": 0.,
        "norm": 1.
    },
    "base_integrator_config": {
        "checkpoint_on_cuda": False,
        "n_bins": 30,
        "n_epochs": 20,
        "lr": 1.e-4,
        "n_points_survey":100000,
        "minibatch_size":10000,
        "survey_strategy": "flat",
        "n_iter_survey":10,
    },
    "debug":False,
    "experiment_name": "camel_pretty_plot",
    "keep_history": True
}, check=False)
```

--------------------------------

### Connect to SQLite Database

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmarks_01/01.first_exploration.ipynb

Establishes a connection to the SQLite database named 'benchmarks.db'.

```python
con = sql.connect("benchmarks.db")
```

--------------------------------

### Instantiate Integrator with Custom Iterations

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/library/integrator.html

Instantiate an Integrator with specific numbers of survey and refine iterations. Default values are shown for comparison.

```python
integrator = Integrator(d=d, f=f, n_iter_survey=3, n_iter_refine=5) # Default values
```

--------------------------------

### Import Benchmark and Integrand Utilities

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/notebooks/2021.08.30.pretty_2d_plots.ipynb

Imports specific classes for benchmarking and various integrand types used in the experiments.

```python
from utils.benchmark.vegas_benchmarks import VegasRandomHPBenchmarker
from utils.config.loaders import get_sql_types
from zunis.utils.config.configuration import Configuration

from utils.integrands.pretty import CircleLineIntegrand, SineIntegrand, SineLineIntegrand
from utils.integrands.gaussian import DiagonalGaussianIntegrand
from utils.integrands.camel import CamelIntegrand, KnownSymmetricCamelIntegrand, SymmetricCamelIntegrand
from utils.integrands.volume import HyperrectangleVolumeIntegrand, HypersphereVolumeIntegrand
```

--------------------------------

### IntegratorSampler.sample()

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Samples using an integrator.

```APIDOC
## IntegratorSampler.sample()

### Description
Samples using an integrator.

### Method
(Method signature from source)

### Parameters
(No parameters explicitly documented)

### Response
(No response details explicitly documented)
```

--------------------------------

### Run Camel Integrand Benchmark

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/notebooks/2021.08.30.pretty_2d_plots.ipynb

Creates a deep copy of the base configuration and runs the benchmark using the camel_pretty_plot function.

```python
config = deepcopy(base_config)
result,integrator = camel_pretty_plot(config)
```

--------------------------------

### Benchmarker.run()

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Executes the benchmarking process.

```APIDOC
## Benchmarker.run()

### Description
Executes the benchmarking process.

### Method
(Method signature from source)

### Parameters
(No parameters explicitly documented)

### Response
(No response details explicitly documented)
```

--------------------------------

### GenericTrainerAPI.sample_forward()

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Performs a forward sampling step for a generic trainer API.

```APIDOC
## GenericTrainerAPI.sample_forward()

### Description
Performs a forward sampling step for a generic trainer API.

### Method
(Method signature from source)

### Parameters
(No parameters explicitly documented)

### Response
(No response details explicitly documented)
```

--------------------------------

### create_integrator_config_file

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/api/zunis.utils.config.generators.html

Creates a configuration file for an integrator. It allows specifying the output file path, a base configuration file to inherit from, and whether to force overwrite an existing file. Additional keyword arguments can be used to set or update options within the configuration.

```APIDOC
## create_integrator_config_file

### Description
Create a config file for an integrator.

### Parameters
#### Path Parameters
- **filepath** (str) - path of the file to which a config file will be saved
- **base_config** (str or None) - path of the source config file on which to base the new config. If none, use the default provided with the library
- **force** (bool, False) - whether to overwrite an existing target file

#### Keyword Arguments
- **kwargs** - options that will be set in the new target file. If the option does not already exist in the base config file, the option is created at the top level. Otherwise, the existing option is updated even if it is nested.
```

--------------------------------

### Customize Integrator Configuration

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/integrator.md

Load default integrator configuration, modify specific parameters like 'loss', 'lr', and 'n_bins', and then create an integrator with these customized settings.

```python
from unis.utils.config.loaders import get_default_integrator_config
from zunis.utils.config.loaders import create_integrator_args

config = get_default_integrator_config()
config['loss'] = 'dkl'
config['lr'] = 1.e-4
config['n_bins'] = 100

kwargs = create_integrator_args(config)
integrator = integrator(d=d, f=f, **kwargs)
```

--------------------------------

### VegasSampler.sample()

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Samples using the Vegas algorithm.

```APIDOC
## VegasSampler.sample()

### Description
Samples using the Vegas algorithm.

### Method
(Method signature from source)

### Parameters
(No parameters explicitly documented)

### Response
(No response details explicitly documented)
```

--------------------------------

### SequentialBenchmarker.generate_config_samples

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/benchmarks_api/utils.benchmark.benchmarker.html

Samples configurations sequentially based on the provided dimensions, integrator grid, and integrand grid, interpreting the integrator grid as a sequence.

```APIDOC
## SequentialBenchmarker.generate_config_samples

Sample over dimensions, integrator and integrand configurations from lists of possible option values.

Parameters:

*   **dimensions** (_List[int]_) – list of dimensions to sample from
*   **integrator_grid** (_Dict[str, List[Any]]_) – mapping (option name) -> (list of values) for the integrator
*   **integrand_grid** (_Dict[str, List[Any]]_) – mapping (option name) -> (list of values) for the integrand

Yields:

*   _Tuple[int, Dict[str, Any], Dict[str, Any]]_ – triplets (d, integrator_config, integrand_params) that can be used to sample configurations
```

--------------------------------

### StatefulTrainer Class

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/api/zunis.training.weighted_dataset.stateful_trainer.html

Initializes the StatefulTrainer with specified parameters for dimensionality, loss function, flow model, prior distribution, and training options.

```APIDOC
## StatefulTrainer

### Description
High-level API for stateful trainers using weighted datasets (dataset consisting of tuples of point, function value, point pdf).

### Parameters
- **d** (int) - dimensionality of the space
- **loss** (str or function) - loss function. If this argument is a string, it is mapped to a function using `zunis.training.weighted_dataset.stateful_trainer.loss_map`
- **flow** (str or `zunis.models.flows.general_flow.GeneralFlow`) - if this variable is a string, it is a cell key used in `zunis.models.flows.sequential.repeated_cell.RepeatedCellFlow` otherwise it can be an actual flow model
- **flow_prior** (None or str or `zunis.models.flows.sampling.FactorizedFlowSampler`) - PDF used for sampling latent space. If None (default) then use the “natural choice” defined in the class variable `zunis.training.weighted_dataset.stateful_trainer.StatefulTrainer.default_flow_priors`. A string argument will be mapped using `zunis.training.weighted_dataset.stateful_trainer.StatefulTrainer.flow_priors`
- **flow_options** (None or dict) - options to be passed to the `zunis.models.flows.sequential.repeated_cell.RepeatedCellFlow` model if `flow` is a string
- **prior_options** (None or dict) - options to be passed to the latent prior constructor if a “natural choice” prior is used i.e. if `flow_prior` is `None` or a `str`
- **device** - device on which to run the model and the sampling
- **n_epochs** (int) - number of epochs per batch of data during training
- **optim** (None or torch.optim.Optimizer sublcass) - optimizer to use for training. If none, default Adam is used
```

--------------------------------

### Display DataFrame

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/exploration/finding_gaussian_camel_benchmark_setup.ipynb

Displays the contents of the 'd_agnostic_setups' DataFrame, showing the combined sigma mappings for Gaussian and Camel distributions.

```python
d_agnostic_setups
```

--------------------------------

### Running Integrator.integrate with Custom Iterations

Source: https://context7.com/ndeutschmann/zunis/llms.txt

Demonstrates how to execute the two-phase integration process using `Integrator.integrate()`, allowing for custom overrides of survey and refine step counts at call time. The `history` DataFrame provides a detailed step-by-step breakdown of the integration.

```python
import torch
from zunis.integration import Integrator

device = torch.device("cpu")
d = 2

def f(x):
    # Gaussian peak at center of hypercube
    return torch.exp(-50 * ((x - 0.5) ** 2).sum(axis=1))

integrator = Integrator(f=f, d=d, device=device, n_iter=5)

# Default call — uses n_iter_survey and n_iter_refine set at construction
result, uncertainty, history = integrator.integrate()

# Override iteration counts at call time
result, uncertainty, history = integrator.integrate(
    n_survey_steps=3,
    n_refine_steps=8,
)
print(f"{result:.4e} +/- {uncertainty:.2e}")

# Inspect per-step breakdown
print(history.to_string())
#    integral      error  n_points    phase
# 0  0.003141   2.1e-04    100000   survey
# ...
# 3  0.003138   1.8e-04    100000   refine
```

--------------------------------

### BasicTrainer.sample_forward()

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Performs a forward sampling step during training.

```APIDOC
## BasicTrainer.sample_forward()

### Description
Performs a forward sampling step during training.

### Method
(Method signature from source)

### Parameters
(No parameters explicitly documented)

### Response
(No response details explicitly documented)
```

--------------------------------

### Load and Prepare Benchmark Data

Source: https://github.com/ndeutschmann/zunis/blob/master/experiments/benchmarks/benchmarks_04/01.camel_default_benchmarks_figures.ipynb

Loads benchmark data from a SQL database, customizes data types for SQL storage, and merges it with external data containing integrand parameters. Ensure 'benchmarks.db' and the CSV file exist.

```python
dtypes = get_sql_types()
dtypes["value_history"] = PickleType

df = read_pkl_sql("benchmarks.db", "camel_defaults", dtypes=dtypes)
df.columns = df.columns.astype(str)
d_sigmas = pd.read_csv('../../exploration/gaussian_camel_integrands.csv')
d_sigma_camel = d_sigmas[['d','sigma_camel','sigma_1d','relative_std_camel']].rename(columns=
                                                                     {
                                                                         "sigma_camel":'s',
                                                                         'relative_std_camel':'relative_std'
                                                                     })

df = df.merge(d_sigma_camel,on=["d","s"],how="left")
```

--------------------------------

### Module: utils.config

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Configuration utilities.

```APIDOC
## module utils.config

### Description
Contains utility functions for handling configuration.

### Endpoint
benchmarks_api/utils.config.html#module-utils.config
```

--------------------------------

### sample_forward

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/api/zunis.training.weighted_dataset.weighted_dataset_trainer.html

Samples points using the model.

```APIDOC
## sample_forward

### Description
Sample points using the model.

### Method
Not specified (likely a method call on an object)

### Parameters
* **_n_points_** (int) - The number of points to sample.
```

--------------------------------

### Train on PyTorch Tensor Sample

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/library/tutorial/preeval.html

Use this when your pre-evaluated sample is available as PyTorch tensors. Ensure tensors are on the same device and in the correct 3-tuple format (points, pdf values, function values).

```python
import torch
from zunis.integration import Integrator

device = torch.device("cuda")

d = 2

def f(x):
    return x[:,0]**2 + x[:,1]**2

integrator =  Integrator(d=d, f=f, survey_strategy='fixed_sample', device=device, n_points_survey=1000)

n_points = 1000
# Uniformly sampled points
x = torch.rand(n_points,d,device=device)
# x.shape = (n_points,d)

px = torch.ones(n_points, device=device)
# px.shape = (n_points,)

# Function values
fx = f(x)

sample = x, px, fx
integrator.set_sample(sample)
result, uncertainty, history = integrator.integrate()
```

--------------------------------

### Module: zunis.integration.dkltrainer_integrator

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Integrator using DKL trainer.

```APIDOC
## module zunis.integration.dkltrainer_integrator

### Description
An integrator that utilizes a DKL (Deep Kernel Learning) trainer.

### Endpoint
api/zunis.integration.dkltrainer_integrator.html#module-zunis.integration.dkltrainer_integrator
```

--------------------------------

### Instantiate and Use an Integrator

Source: https://github.com/ndeutschmann/zunis/blob/master/doc_build/library/integrator.md

Define a function and use it to instantiate an `Integrator`. The `integrate` method then computes the integral and its uncertainty.

```python
from zunis.integration import Integrator

def f(x):
    return x[:,0]**2 + x[:,1]**2

integrator = Integrator(d=d,f=f)
```

```python
result, uncertainty, history = integrator.integrate()
print(f"{result:.3e} +/- {uncertainty:.3}")
# > 6.666e-01 +/- 4.69e-05
```

--------------------------------

### BasicStatefulTrainer.train_on_target_batches_from_posterior

Source: https://github.com/ndeutschmann/zunis/blob/master/docs/genindex.html

Trains the BasicStatefulTrainer on target batches sampled from the posterior distribution.

```APIDOC
## BasicStatefulTrainer.train_on_target_batches_from_posterior

### Description
Trains the BasicStatefulTrainer using target batches drawn from the posterior distribution.

### Method
(Not specified in source, likely a Python method call)

### Endpoint
(Not applicable, this is an SDK method)

### Parameters
(Parameters not specified in source)

### Request Example
(Not applicable)

### Response
(Response details not specified in source)
```