← Về thư mục
📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / fluidsim / references / installation.md

Installation, native dependencies, and backends

Supported baseline

Verified 2026-07-23:

The FluidSim installation page still says Python >=3.9; current PyPI and pyproject.toml metadata say >=3.11. Use the package metadata for 0.9.0.

FluidSim 0.9.0 declares:

The broad upstream constraints are compatibility ranges, not a reproducible environment. Record the generated lock and artifact hashes.

Reproducible uv environment

Preferred project workflow:

uv init --python 3.11
uv add "fluidsim[fft]==0.9.0" "fluidfft==0.4.5" "pyFFTW==0.15.1"
uv lock
uv sync --frozen

Check the lock into the study repository. Record:

For an isolated smoke environment:

uv venv --python 3.11
uv pip install "fluidsim[fft]==0.9.0" "fluidfft==0.4.5" "pyFFTW==0.15.1"

This pins direct dependencies but does not replace a lock for transitive reproducibility.

Bare fluidsim==0.9.0 supports parts of the framework and analysis stack, but a verified local smoke test found that importing NS2D succeeded while Simul.create_default_params() failed without fluidfft. Install the fft extra for pseudospectral solvers.

Sequential FFT choices

The non-compiling path is:

uv add "fluidsim[fft]==0.9.0" "fluidfft==0.4.5" "pyFFTW==0.15.1"

FluidFFT 0.4.5 registers:

The native FFTW plugin is separately versioned:

uv add "fluidfft-fftw==0.0.1"

The 0.0.1 plugin versions are stable PyPI releases from February 2024 and are versioned independently from FluidFFT 0.4.5; they are not proof of compatibility with a particular native stack. Before installation, verify that each PyPI project links to the official fluiddyn/fluidfft monorepo, review the plugin source, resolve through uv.lock, retain artifact hashes, and use uv sync --frozen. Do not trust a familiar distribution name alone.

It provides:

It requires discoverable FFTW headers/libraries and a working native build toolchain. pyFFTW wheels bundle supported binaries on many 64-bit platforms; source builds require FFTW >=3.3, Cython, and a compiler.

Discover only methods actually installed on the current host:

fluidfft-get-methods

Do not copy a method name from documentation and assume its plugin or ABI is usable. Run a tiny transform/FluidSim pilot and record the selected method.

MPI and distributed FFT

Nothing in this skill launches MPI or submits a scheduler job. First identify:

Then lock Python packages:

uv add "mpi4py==4.1.2" \
  "fluidfft-mpi-with-fftw==0.0.1" \
  "fluidfft-fftwmpi==0.0.1"
uv lock

Plugin methods:

The package names use hyphens on PyPI; FluidFFT's optional dependency keys map to distributions such as fluidfft-mpi_with_fftw. Let the lock resolve the canonical distribution and preserve it.

mpi4py wheels still need a compatible MPI runtime. Convenience MPI wheels can lack GPU awareness or site fabric support; mpi4py recommends system/vendor MPI for production. Never mix an mpi4py build from one implementation with a different launcher/runtime. Verify import and rank identity inside a manually allocated tiny job before FluidSim.

The primary FluidFFT paper shows that the fastest backend depends on array shape, machine, and process count; one-dimensional decomposition can be useful at low rank count, while pencil/two-dimensional decomposition is needed to avoid decomposition limits at high rank count. These are benchmark-context claims, not universal backend recommendations.

GPU status

The 2019 FluidFFT paper describes a cuFFT path, and the repository README still lists cuFFT. However:

Therefore there is no supported one-line GPU installation in this skill. Do not install nvidia-cufft-* and claim FluidSim acceleration: a runtime library alone does not provide a registered FluidFFT method. A GPU experiment must pin CUDA, driver, compiler, plugin source revision, Python packages, precision, hardware, and validation tests separately.

Native build prerequisites

Depending on selected plugins:

The P3DFFT plugin also recognizes P3DFFT_DIR, or P3DFFT_LIB_DIR/P3DFFT_INCLUDE_DIR. Record values but never alter global shell startup files automatically.

HDF5 and netCDF4

FluidSim 0.9 physical-state files default to netCDF4/HDF5 .nc; spectra remain HDF5 .h5. Standard h5py wheels are usually non-MPI, which is normally appropriate because output is coordinated by FluidSim. Parallel HDF5 is a separate native build requiring:

Do not build MPI-enabled h5py merely because the simulation uses MPI. Confirm the intended I/O path and test a tiny file first.

Runtime paths and backend selection

Official variables:

export FLUIDSIM_PATH="/approved/bounded/results-root"
export FLUIDDYN_PATH_SCRATCH="/approved/bounded/scratch-root"
export FLUIDSIM_TYPE_FFT2D="fft2d.with_pyfftw"
export FLUIDSIM_TYPE_FFT3D="fft3d.with_pyfftw"

Set only after checking:

Prefer params.oper.type_fft for an explicit per-run choice. Environment variables affect process-wide behavior and must be captured in provenance.

FluidFFT is also sensitive to TRANSONIC_BACKEND; changing it changes generated code/performance and belongs in provenance.

Verification ladder

Run in this order:

  1. Dependency-free bundled CLI helps.
  2. Import/version/solver parameter smoke in an isolated pinned environment.
  3. Tiny serial 8x8 or 16x16 no-output initialization and one step.
  4. Tiny serial output round-trip and restart.
  5. Backend-specific FFT test.
  6. Manually allocated two-rank smoke, only if MPI is required.
  7. Representative bounded pilot with resource monitoring.

Do not run the full upstream test suite or MPI tests on a login node without approval; they can compile, spawn processes, and consume resources.

Sources (verified 2026-07-23)