foxes#

Documentation
GitHub
Examples
Cite [3]

FOXES is an open-source wind farm and wake modelling framework in Python by Fraunhofer IWES. It is based on the fast vectorized evaluation of engineering wake models and has been optimized for runs of large scenarios, e.g., long-term timeseries input data combined with large wind farms with up to thousands of turbines.

Configuration Options#

foxes shares most configuration options with PyWake via the analysis.yaml file. Refer to the PyWake documentation for common options.

foxes-specific features:

Optimized for large wind farms (1000+ turbines)
Efficient chunked processing for long time series
Multiple computation engines (multiprocessing, threading, dask)
Native WindIO integration via foxes.input.yaml.windio

Engine Selection#

foxes supports multiple computation engines:

default: Single-threaded (good for debugging)
process: Multi-process parallelization (recommended for CPU-bound)
thread: Multi-threaded parallelization
dask: Distributed computing with Dask

API Reference#

Usage#

Command Line:

wifa_foxes path/to/system.yaml

# With options
wifa_foxes system.yaml -o results -n 4 -v 1

Python:

from wifa.foxes_api import run_foxes

# Basic usage
farm_results, point_results, outputs = run_foxes("path/to/system.yaml")

# With parallel processing
farm_results, point_results, outputs = run_foxes(
    "system.yaml",
    engine="process",
    n_procs=4,
    chunksize_states=1000
)

Command Line Options#

wifa_foxes input.yaml [options]

Options:
  -o, --output_dir        Output directory
  -e, --engine            Computation engine (default, process, thread, dask)
  -n, --n_procs           Number of processes for parallel execution
  -c, --chunksize_states  Chunk size for states dimension
  -C, --chunksize_points  Chunk size for points dimension (default: 5000)
  -it, --iterative        Use iterative algorithm (for blockage)
  -v, --verbosity         Verbosity level (0=silent, 1=normal)

CLI Examples#

# Parallel run with 8 processes
wifa_foxes system.yaml -e process -n 8

# Custom output directory, verbose
wifa_foxes system.yaml -o my_results -v 1

# Large time series with chunking
wifa_foxes system.yaml -e process -n 4 -c 1000

# Batch processing with all available cores
wifa_foxes system.yaml -e process -n $(nproc) -c 5000

# Run all example cases
for case in examples/cases/*/wind_energy_system/system.yaml; do
    wifa_foxes "$case" -o "results/$(dirname $(dirname $case) | xargs basename)"
done

wifa.foxes_api.run_foxes(input_yaml, input_dir=None, output_dir=None, engine='default', n_procs=None, chunksize_states=None, chunksize_points=None, verbosity=1, **kwargs)#

Run a foxes simulation from WindIO input.

Parameters:

input_yaml (str or dict) – Path to WindIO YAML file or pre-loaded dictionary
input_dir (str, optional) – Base directory for relative paths in input
output_dir (str, optional) – Output directory
engine (str) – Computation engine (default, process, thread, dask)
n_procs (int, optional) – Number of processes for parallel execution
chunksize_states (int, optional) – Chunk size for states dimension
chunksize_points (int, optional) – Chunk size for points dimension
verbosity (int) – Verbosity level (0=silent)
kwargs – Additional parameters for foxes.input.yaml.run_dict

Returns:

Tuple of (farm_results, point_results, outputs)

Return type:

tuple

Example:

from wifa.foxes_api import run_foxes

farm_results, point_results, outputs = run_foxes(
    "system.yaml",
    engine="process",
    n_procs=8
)
print(farm_results.P)  # Power per turbine

Outputs#

Returns a tuple of three elements:

farm_results: xarray.Dataset with per-turbine results
point_results: xarray.Dataset with flow field results (if requested)
outputs: List of additional output tuples