Brownian Rod Taylor Dispersion

This repository contains the numerical source code accompanying the manuscript

J. Feng and X. Chu, Shear alignment and tensorial Taylor--Aris dispersion of Brownian rods in a circular tube.

It provides the calculation pipeline without manuscript plotting routines. The committed reference files are numerical tables and compact arrays used to verify the paper calculations.

Included numerical methods

• Real spherical-harmonic solution of the steady three-dimensional orientation Fokker--Planck equation.
• Conservative Scharfetter--Gummel finite volumes on orientation space for strongly aligned rods.
• Perrin translational mobilities and the local cylindrical transport tensor.
• Covariant radial invariant measure, cell problem, drift and finite-Péclet effective diffusivity.
• Radial finite-element Sturm--Liouville modes and finite-time moment propagation.
• Conservative axisymmetric r-z finite volumes implemented with NVIDIA Warp.
• Coupled transverse-position/orientation Brownian dynamics implemented with CuPy CUDA kernels.
• Poiseuille and prescribed power-law velocity profiles.

The cylindrical connection term involving Dphiphi is retained throughout the radial equilibrium, finite-volume and spectral formulations.

Installation

Python 3.10 or newer is required.

git clone https://github.com/JingsenFeng/brownian-rod-taylor-dispersion.git
cd brownian-rod-taylor-dispersion
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"

Warp and CuPy are optional because the core closure and long-time calculations run on a CPU.

# Axisymmetric finite-volume solver
python -m pip install -e ".[gpu-warp]"

# Monte Carlo solver for CUDA 12
python -m pip install -e ".[gpu-cuda12]"

Select the CuPy package appropriate for the installed CUDA toolkit when CUDA 12 is not used.

Verify the release

The following commands check all committed reference hashes, recompute a representative production case and run the regression suite.

python scripts/verify_reference_data.py
python -m pytest

The CPU suite checks the classical spherical value kappa=1/192, the covariant stationary measure, conservative mixed fluxes, angular normalization, tensor trace, spectral parity and the Appendix A high-shear refinement. The Warp parity test runs on the CPU when Warp is installed and is skipped otherwise.

Quick calculation

The complete 121-point long-time scan can be regenerated directly from the committed local tensor table.

python scripts/compute_long_time_coefficients.py

This writes CSV and NPZ data under results/long_time/. On the development workstation the calculation takes less than one second. Numerical arrays from this command agree element by element with reference_data/covariant_long_time_sweep.npz under the tested NumPy and SciPy versions.

Other entry points include

python scripts/export_covariant_profile.py --p 1000 --per 1000 --pe 10000
python scripts/run_spectral_validation.py --p 1000 --per 1000 --pe 10000
python scripts/run_high_q_refinement.py --help
python scripts/run_rz_validation.py --help
python scripts/run_mc_validation.py --help

Full production commands, hardware notes and the correspondence between scripts and manuscript results are given in REPRODUCIBILITY.md.

Repository layout

src/brownian_rod_dispersion/   numerical library
scripts/                       calculation-only command-line programs
tests/                         analytical and numerical regression tests
reference_data/                compact paper reference arrays and CSV files
.github/workflows/             CPU continuous integration

Generated output is written below results/ and is ignored by Git. No figure-generation source, manuscript file, reviewer material or large two-dimensional field output is included.

Reference-data integrity

Checksums are stored in reference_data/SHA256SUMS and can be checked independently with

cd reference_data
sha256sum --check SHA256SUMS

Citation

Please cite the associated manuscript and this software release. Machine-readable citation metadata are provided in CITATION.cff.

License

The code is released under the Apache License 2.0. See LICENSE and NOTICE.