# Download package — user instructions

**Product:** FX Options companion Python (worked examples)  
**Book:** *FX Options: Pricing, Hedging, Exotics, Risk and Institutional Practice*  
**Support:** fxoptions@rondanini.com

This guide is for the **ZIP / folder download**. For the browser product, see [PLAYGROUND.md](PLAYGROUND.md).  
Start overview: [START_HERE.md](START_HERE.md).

---

## What you received

```
playground-content/
  START_HERE.md       ← overview (read first)
  PLAYGROUND.md       ← browser instructions
  USER_GUIDE.md       ← this file
  README.md           ← developer / maintainer notes
  manifest.json       ← catalogue of all 193 examples
  run_examples.py     ← batch runner
  verify_bundle.py    ← integrity check
  examples/
    gk.py             ← shared Garman–Kohlhagen helpers
    var.py, vol_models.py, …
    ch04/WE-4.*.py
    ch08/… through ch30/
```

You need **Python 3.10 or newer**, plus **NumPy** and **SciPy**.

---

## Setup (one time)

### Windows (PowerShell)

```powershell
cd path\to\playground-content
python --version
python -m pip install --upgrade pip
python -m pip install numpy scipy
```

### macOS / Linux

```bash
cd path/to/playground-content
python3 --version
python3 -m pip install --upgrade pip
python3 -m pip install numpy scipy
```

If `python` is not found, install Python from https://www.python.org and ensure “Add Python to PATH” is enabled (Windows).

---

## Verify the package

From inside `playground-content`:

```bash
python verify_bundle.py
```

Expected: a message that **193** validated examples are present and bundle integrity is OK.

If files are missing, re-download the ZIP — do not ship or share a truncated tree.

---

## Run a single worked example

1. Look up the example in the book (e.g. Example 9.4).
2. Find the matching file under `examples/ch09/` (names start with `WE-9.4_…`).
3. Run it:

```bash
python examples/ch09/WE-9.4_turnbull-wakeman-pricing.py
```

On macOS/Linux you may need `python3` instead of `python`.

Successful scripts print labelled results and exit with code **0**.  
Failed asserts print a clear error and exit non-zero.

---

## Run many examples

```bash
# All examples on disk (can take several minutes; Monte Carlo is slower)
python run_examples.py

# One chapter
python run_examples.py --chapter 9

# Longer timeout for heavy Monte Carlo
python run_examples.py --timeout 180
```

Optional self-check of the shared pricing helper:

```bash
python examples/gk.py
```

---

## How examples map to the book

| Book label | Package file pattern |
|------------|----------------------|
| Example 8.4 / WE-8.4 | `examples/ch08/WE-8.4_*.py` |
| Example 20.15 | `examples/ch20/WE-20.15_*.py` |

`manifest.json` lists every ID, title, chapter, and relative `py_file` path.

Chapters **1–3** and **5–7** have no download scripts (numerical exposition only in the manuscript).

---

## Requirements and limits

- **Offline / educational use only** — no live market data connectors.
- **NumPy / SciPy only** for the shipped examples (designed to mirror the Pyodide playground).
- Do **not** treat illustrative inputs as tradable prices.
- Before any production or risk-management use: add your own tests, model governance, and independent benchmarks.

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `python` not found | Install Python 3.10+ and reopen the terminal |
| `No module named numpy` | `python -m pip install numpy scipy` |
| `verify_bundle.py` fails | Re-extract the full ZIP; ensure you are in `playground-content` |
| Wrong directory | Scripts expect to be run from `playground-content` (or with paths as in the examples above) |
| Assertion error vs book | Confirm example ID; then email support with book page + console output |
| Monte Carlo timeout | Re-run with `--timeout 180` or run that single file alone |

---

## Report a problem

Email: **fxoptions@rondanini.com**

Please send:

1. Example ID / file path  
2. OS and `python --version`  
3. Full console output (or screenshot)  
4. Whether numbers disagree with a specific book page  
5. Order email / proof of purchase if access-related  

Browser playground issues: same address — note “playground” in the subject.

Other contacts:

- Education: education@rondanini.com  
- General: support@rondanini.com  
- Playground: https://rondanini.com/fxoptionsplayground  
- Education site: https://education.rondanini.com