10  Environment variables

Logging and GPU selection for Wake CFD v0.7.0

10.1 Overview

Wake CFD executes with default settings without environment variable configuration. Configure environment variables only when log files become excessively large, when selecting specific GPUs on multi-GPU servers, or when reducing log file count in MPI runs.

Case configuration belongs in JSONC input files. Environment variables control only settings that must be determined before the solver reads the input file—logging, for example, because the JSONC parser itself uses the logger.

10.2 Setting environment variables

10.2.1 Command-line (one-time use)

Windows PowerShell:

$env:WAKE_LOG_LEVEL = "info"
.\wake_3d_mixed.exe case.jsonc

Linux Bash:

WAKE_LOG_LEVEL=info ./wake_3d_mixed case.jsonc

This sets the variable for one execution only.

10.2.2 ~/.wake/env file (persistent defaults)

Create a ~/.wake/env file in the home directory to avoid re-exporting environment variables in every run script. The solver reads this file on startup and applies it to the process environment.

File location: - Linux/Mac: ~/.wake/env - Windows: %USERPROFILE%\.wake\env (e.g., C:\Users\YourName\.wake\env)

Example ~/.wake/env:

# Reduce log verbosity
WAKE_LOG_LEVEL=info

# Only rank 0 logs in MPI runs
WAKE_LOG_SCOPE=master

File syntax: - Lines beginning with # and blank lines are ignored - Use KEY=VALUE format - Surrounding whitespace is trimmed

Precedence:

Built-in defaults < ~/.wake/env < Shell environment variables

The file does not override variables already exported in the shell. To override a file setting for one run, export the variable on the command line:

WAKE_LOG_LEVEL=trace ./wake_3d_mixed case.jsonc  # overrides ~/.wake/env

When the file does not exist, the solver proceeds with built-in defaults.

10.3 Logging

10.3.1 WAKE_LOG_LEVEL

Controls the minimum severity recorded in .log files.

Value Meaning Application
trace Most detailed Debugging solver behavior
debug Development diagnostics Investigating unexpected results
info Execution flow Reduce log size (recommended)
warn Warnings and above Minimal logging
error Errors only Production runs

Default (v0.7.0 technical preview): Current builds use debug when WAKE_LOG_LEVEL is unset. The default will be reduced as releases stabilize.

Scenario: Reduce log file size

Log files growing to several GB indicate excessive detail. Set WAKE_LOG_LEVEL=info to reduce verbosity.

Windows PowerShell:

$env:WAKE_LOG_LEVEL = "info"
.\wake_3d_mixed.exe case.jsonc

Linux Bash:

WAKE_LOG_LEVEL=info ./wake_3d_mixed case.jsonc

Or add to ~/.wake/env:

WAKE_LOG_LEVEL=info

Note: Console convergence history is independent of this variable. Console output is controlled by monitoring.console in the JSONC input file.

10.3.2 WAKE_LOG_SCOPE

Reduces the number of log files in MPI runs.

Value Behavior Application
Unset Every rank creates its own .rank<N>.log file Investigating rank-specific problems
master Only rank 0 creates a log file; other ranks do not Normal MPI execution (recommended)

Scenario: Reduce log file count in MPI runs

Executing mpirun -n 100 creates 100 separate log files by default. Set WAKE_LOG_SCOPE=master to create only one log file from rank 0.

Windows PowerShell:

$env:WAKE_LOG_SCOPE = "master"
mpirun -n 4 wake_3d_mixed.exe case.jsonc

Linux Bash:

WAKE_LOG_SCOPE=master mpirun -n 4 ./wake_3d_mixed case.jsonc

This reduces file count and I/O overhead in high-rank runs. Disable only when diagnosing a problem specific to one rank.

10.4 GPU selection

10.4.1 CUDA_VISIBLE_DEVICES

This standard CUDA environment variable restricts which GPUs Wake CFD can access. Use this on multi-GPU servers to reserve specific GPUs or avoid GPUs in use by other jobs.

Scenario: Select specific GPUs

On a server with 4 GPUs (0, 1, 2, 3), restrict Wake CFD to GPUs 2 and 3 by setting CUDA_VISIBLE_DEVICES=2,3.

Windows PowerShell:

$env:CUDA_VISIBLE_DEVICES = "2,3"
mpirun -n 2 wake_3d_mixed.exe case.jsonc

Linux Bash:

CUDA_VISIBLE_DEVICES=2,3 mpirun -n 2 ./wake_3d_mixed case.jsonc

Single GPU:

CUDA_VISIBLE_DEVICES=1 ./wake_3d_mixed case.jsonc  # Use only GPU 1

At startup, the solver logs the GPU list. When CUDA_VISIBLE_DEVICES is set, the log indicates that the GPU list was filtered.

10.5 Summary

Variable Values Application
WAKE_LOG_LEVEL trace, debug, info, warn, error Log files excessively large
WAKE_LOG_SCOPE master MPI runs create excessive log files
CUDA_VISIBLE_DEVICES GPU index list (e.g., 0,2,3) Select specific GPUs on multi-GPU servers

Typical persistent defaults:

# ~/.wake/env
WAKE_LOG_LEVEL=info
WAKE_LOG_SCOPE=master

One-time override:

# Windows PowerShell
$env:WAKE_LOG_LEVEL = "trace"
.\wake_3d_mixed.exe case.jsonc

# Linux Bash
WAKE_LOG_LEVEL=trace ./wake_3d_mixed case.jsonc