PyApprox Tutorial Library
After completing this tutorial, you will be able to:
This tutorial assumes you have:
Create a dedicated environment for PyApprox:
To install the latest version directly from the repository:
To clone the repository for local development or contributing:
Alternatively, use the provided environment.yml to create a fully configured conda environment with all dependencies:
Let’s verify that PyApprox is installed correctly by importing key modules.
PyApprox uses a backend-agnostic design that allows the same code to run with either NumPy or PyTorch arrays. This enables:
For these tutorials, we use the NumPy backend exclusively.
The backend provides methods for common array operations:
import numpy as np
# Array creation
zeros = bkd.zeros((3, 2))
ones = bkd.ones((2, 3))
eye = bkd.eye(3)
# Mathematical operations
y = bkd.array([[1.0], [2.0], [3.0]])
result = bkd.sum(y)
print(f"Sum: {result}")
# Linear algebra
A = bkd.array([[1.0, 2.0], [3.0, 4.0]])
b = bkd.array([[5.0], [6.0]])
x_solve = bkd.solve(A, b)
print(f"Solution to Ax=b: {x_solve.flatten()}")Sum: 6.0
Solution to Ax=b: [-4. 4.5]Benchmarks are pre-configured test problems with known solutions. Let’s load the Lotka-Volterra ecosystem model that we’ll use throughout these tutorials.
Benchmark name: lotka_volterra_3species
Number of parameters: 12
Number of states: 3The Lotka-Volterra model describes the population dynamics of three competing species. We’ll explore this model in detail in subsequent tutorials.
PyApprox follows consistent array shape conventions:
| Array Type | Shape | Description |
|---|---|---|
| Input samples | (nvars, nsamples) |
Variables as rows, samples as columns |
| Output values | (nqoi, nsamples) |
Quantities of interest as rows |
| Single sample | (nvars, 1) |
Always 2D, even for one sample |
(nvars, nsamples)NumpyBkd() backend is used for all tutorials unless otherwise noted(Easy) Create a 4x10 array of random numbers using the backend and compute its column-wise mean.
(Medium) Load the ishigami_3d benchmark and print its name, domain bounds (benchmark.domain().bounds()), and number of variables (benchmark.domain().nvars()).
(Challenge) Explore the backend’s linear algebra capabilities by solving a 5x5 random linear system \(Ax = b\).
Now that your environment is set up, continue to:
---
title: "Setting Up Your Environment"
subtitle: "PyApprox Tutorial Library"
description: "Configure Python environment for uncertainty quantification with PyApprox"
prerequisites: []
tags:
- setup
format:
html:
code-fold: false
code-tools: true
toc: true
execute:
echo: true
warning: false
jupyter: python3
render_time: 9
---
::: {.callout-tip collapse="true"}
## Download Notebook
[Download as Jupyter Notebook](notebooks/setup_environment.ipynb)
:::
## Learning Objectives
After completing this tutorial, you will be able to:
- Install PyApprox and its dependencies
- Set up a conda environment for UQ computations
- Import and verify key PyApprox modules
- Understand the backend system for array operations
## Prerequisites
This tutorial assumes you have:
- Python 3.10 or later installed
- Basic familiarity with conda or pip package management
- A terminal or command prompt
## Installation
### Option 1: Conda (Recommended)
Create a dedicated environment for PyApprox:
```bash
conda create -n pyapprox python=3.12
conda activate pyapprox
pip install pyapprox
```
### Option 2: Pip Only
```bash
pip install pyapprox
```
### Install Latest from GitHub
To install the latest version directly from the repository:
```bash
pip install "pyapprox[all] @ git+https://github.com/sandialabs/pyapprox.git"
```
### Development Installation
To clone the repository for local development or contributing:
```bash
git clone https://github.com/sandialabs/pyapprox.git
cd pyapprox
pip install -e ".[all]"
```
Alternatively, use the provided `environment.yml` to create a fully configured conda environment with all dependencies:
```bash
git clone https://github.com/sandialabs/pyapprox.git
cd pyapprox
conda env create -f environment.yml
conda activate pyapprox
pip install -e ".[all]"
```
## Verifying Installation
Let's verify that PyApprox is installed correctly by importing key modules.
```{python}
# Core backend for array operations
from pyapprox.util.backends.numpy import NumpyBkd
# Benchmark problems for testing
from pyapprox.benchmarks import (
lotka_volterra_3species,
ishigami_3d,
)
print("pyapprox imported successfully!")
```
## The Backend System
PyApprox uses a backend-agnostic design that allows the same code to run with either NumPy or PyTorch arrays. This enables:
- **NumPy backend**: Standard numerical computing, CPU-based
- **PyTorch backend**: GPU acceleration, automatic differentiation
For these tutorials, we use the NumPy backend exclusively.
### Creating a Backend
```{python}
from pyapprox.util.backends.numpy import NumpyBkd
# Create the NumPy backend
bkd = NumpyBkd()
# The backend provides array creation and operations
x = bkd.array([[1.0, 2.0, 3.0]])
print(f"Array shape: {x.shape}")
print(f"Array values: {x}")
```
### Backend Operations
The backend provides methods for common array operations:
```{python}
import numpy as np
# Array creation
zeros = bkd.zeros((3, 2))
ones = bkd.ones((2, 3))
eye = bkd.eye(3)
# Mathematical operations
y = bkd.array([[1.0], [2.0], [3.0]])
result = bkd.sum(y)
print(f"Sum: {result}")
# Linear algebra
A = bkd.array([[1.0, 2.0], [3.0, 4.0]])
b = bkd.array([[5.0], [6.0]])
x_solve = bkd.solve(A, b)
print(f"Solution to Ax=b: {x_solve.flatten()}")
```
## Loading a Benchmark
Benchmarks are pre-configured test problems with known solutions. Let's load the Lotka-Volterra ecosystem model that we'll use throughout these tutorials.
```{python}
# Create backend and load benchmark
bkd = NumpyBkd()
benchmark = lotka_volterra_3species(bkd)
# Examine benchmark properties
print(f"Benchmark name: {benchmark.name()}")
print(f"Number of parameters: {benchmark.nparams()}")
print(f"Number of states: {benchmark.nstates()}")
```
The Lotka-Volterra model describes the population dynamics of three competing species. We'll explore this model in detail in subsequent tutorials.
## Array Shape Conventions
PyApprox follows consistent array shape conventions:
| Array Type | Shape | Description |
|------------|-------|-------------|
| Input samples | `(nvars, nsamples)` | Variables as rows, samples as columns |
| Output values | `(nqoi, nsamples)` | Quantities of interest as rows |
| Single sample | `(nvars, 1)` | Always 2D, even for one sample |
```{python}
# Example: 3 variables, 5 samples
nvars, nsamples = 3, 5
samples = bkd.array(np.random.rand(nvars, nsamples))
print(f"Samples shape: {samples.shape}")
print(f"First sample (column): {samples[:, 0]}")
```
## Key Takeaways
- PyApprox uses a **backend system** for array operations (NumPy or PyTorch)
- **Benchmarks** provide pre-configured test problems with known solutions
- Arrays follow the convention: **samples as columns** `(nvars, nsamples)`
- The `NumpyBkd()` backend is used for all tutorials unless otherwise noted
## Exercises
1. **(Easy)** Create a 4x10 array of random numbers using the backend and compute its column-wise mean.
2. **(Medium)** Load the `ishigami_3d` benchmark and print its name, domain bounds (`benchmark.domain().bounds()`), and number of variables (`benchmark.domain().nvars()`).
3. **(Challenge)** Explore the backend's linear algebra capabilities by solving a 5x5 random linear system $Ax = b$.
## Next Steps
Now that your environment is set up, continue to:
- [From Models to Decisions Under Uncertainty](models_decisions_uncertainty.qmd) - Why computational models need UQ