Linearized Boltzmann Transport

At every stage, you MUST explain what you are doing and why, in enough detail that the user can:

• Understand the physics behind each step (not just the code)
• Judge whether the choices are correct for their specific system
• Catch errors in the reasoning, formulas, or implementation
• Learn the method well enough to modify it for new situations

This means: explain the physical reasoning, show the key formulas with their meaning, present results with interpretation, and point out where things could go wrong. The user is a physicist — talk to them as a collaborator, not a customer waiting for output.

2. Show Your Work at Every Stage

After completing each stage, you MUST output:

• What was computed — the formulas used and why they are the right ones
• Numerical results in tables — not just figures
• Physical interpretation — what do the numbers mean? Are they reasonable?
• Sanity checks — does this match known limits, sum rules, or dimensional analysis?
• Data files — save all underlying data as .txt/.csv alongside any plots
• What could go wrong — what should the user check? What are the sensitive parameters?

Never produce results without explaining how to verify them. Never produce figures without analysis text explaining what the figure shows, what the user should look for, and what would indicate a problem.

3. Invite Scrutiny, Not Just Approval

At each checkpoint, do NOT simply ask "shall I proceed?" Instead:

• Summarize what was done and the key results
• Point out anything surprising, suspicious, or worth double-checking
• Ask the user if the results make physical sense for their system
• Suggest what specific things they should verify

The goal is a scientific dialogue, not a permission workflow.

4. Never Output Uncertain Analysis as Fact

If you are not confident about a physical interpretation, do NOT write it down as if it were established. Instead:

• Present the numerical results clearly
• State what you are uncertain about
• Ask the user to help interpret

Vague or incorrect analysis is worse than no analysis. The user is the domain expert — let them draw conclusions from clean data. When in doubt, show the numbers and ask.

Pipeline Overview

The pipeline has two phases: Planning (Stages 0–C) and Execution (Stages 1–8). No code is written until the user approves the theory document and coding plan.

digraph pipeline {
    rankdir=TB;

    subgraph cluster_planning {
        label="Planning Phase (no code yet)";
        style=dashed;
        "0. Clarify requirements\n(system, results, scope)" [shape=box];
        "A. Basis assessment\n(does this need expansion?)" [shape=box];
        "B. Theory document\n(write derivation .md, user reviews)" [shape=box];
        "C. Coding plan\n(write plan .md, user reviews)" [shape=box];
    }

    subgraph cluster_execution {
        label="Execution Phase";
        "1. Define system\n(discuss with user)" [shape=box];
        "2. Natural units\n(explain choices)" [shape=box];
        "3. Equilibrium & weight\n(show plots, explain physics)" [shape=box];
        "4. Symmetry & basis\n(present options, explain trade-offs)" [shape=box];
        "5. Collision kernel\n(show matrix structure, verify)" [shape=box];
        "6. Diagnostics\n(present all checks, explain failures)" [shape=box];
        "Diagnostics pass?" [shape=diamond];
        "7. Transport coefficients\n(explain each coefficient, compare RTA)" [shape=box];
        "8. Eigenmode analysis\n(full spectrum, mode-resolved transport)" [shape=box];
    }

    "0. Clarify requirements\n(system, results, scope)" -> "A. Basis assessment\n(does this need expansion?)";
    "A. Basis assessment\n(does this need expansion?)" -> "B. Theory document\n(write derivation .md, user reviews)";
    "B. Theory document\n(write derivation .md, user reviews)" -> "C. Coding plan\n(write plan .md, user reviews)";
    "C. Coding plan\n(write plan .md, user reviews)" -> "1. Define system\n(discuss with user)" [label="user approves"];

    "1. Define system\n(discuss with user)" -> "2. Natural units\n(explain choices)";
    "2. Natural units\n(explain choices)" -> "3. Equilibrium & weight\n(show plots, explain physics)";
    "3. Equilibrium & weight\n(show plots, explain physics)" -> "4. Symmetry & basis\n(present options, explain trade-offs)";
    "4. Symmetry & basis\n(present options, explain trade-offs)" -> "5. Collision kernel\n(show matrix structure, verify)";
    "5. Collision kernel\n(show matrix structure, verify)" -> "6. Diagnostics\n(present all checks, explain failures)";
    "6. Diagnostics\n(present all checks, explain failures)" -> "Diagnostics pass?";
    "Diagnostics pass?" -> "7. Transport coefficients\n(explain each coefficient, compare RTA)" [label="yes"];
    "Diagnostics pass?" -> "5. Collision kernel\n(show matrix structure, verify)" [label="no → explain what's wrong"];
    "7. Transport coefficients\n(explain each coefficient, compare RTA)" -> "8. Eigenmode analysis\n(full spectrum, mode-resolved transport)";
}

Every stage is a dialogue. Explain what you did, show the results with interpretation, point out what the user should verify, and invite questions before continuing.

Stage-by-Stage Protocol

PLANNING PHASE (Stages 0, A, B, C)

No code is written during the planning phase. The goal is to fully understand the problem, work out the theory, and agree on a plan before touching any code.

Stage 0: Clarify Requirements

Before anything else, have a structured conversation with the user to pin down exactly what they need. Ask about each of the following, one at a time:

0a. The physical system

• What particles? (electrons, phonons, magnons, cold atoms, classical gas, ...)
• What dimension and dispersion? (2D parabolic, 3D Dirac, acoustic phonon branch, ...)
• What interactions? (screened Coulomb, contact, deformation potential, ...)
• What scattering channels? (e-e normal, Umklapp, impurity, phonon emission/absorption, ...)
• What regime? (degenerate/non-degenerate, weak/strong coupling, low/high temperature)
• What are the key parameters? ($r_s$, $T/T_F$, $\tau_{\mathrm{mr}}^{-1}$, ...)

0b. The desired results

• Which transport coefficients? ($\sigma$, $\kappa$, Seebeck $S$, viscosity $\eta$, Hall, Nernst, ...)
• Eigenmode analysis? (full spectrum, mode-resolved transport, eigenvector structure, ...)
• RTA comparison? (exact vs RTA, quantify failure)
• Parameter sweeps? (vary $T/T_F$, $r_s$, $\tau_{\mathrm{mr}}^{-1}$, ...)
• What format? (figures + data files, tables, analytical formulas, ...)

0c. Scope and constraints

• Is this a new system or extending an existing calculation?
• Are there known results to benchmark against? (literature values, limiting cases)
• Are there computational constraints? (max matrix size, time budget)
• What level of detail in the output? (quick survey vs publication-quality analysis)

Output: A requirements summary table. Example:

Present this summary to the user and confirm before moving on. Misunderstanding the problem here wastes everything downstream.

Stage A: Basis Assessment

Before choosing a specific basis, assess whether the problem requires a basis function expansion at all, and if so, what kind.

Questions to evaluate

1. Does this problem have continuous degrees of freedom that need discretization?

   • If the collision operator acts in a continuous energy/momentum space → yes, need basis expansion
   • If already on a discrete lattice or finite set of modes → may not need expansion

2. What symmetry can be exploited?

   • Isotropic dispersion → angular-harmonic decomposition (Fourier in 2D, spherical harmonics in 3D) reduces the problem to 1D in energy per angular channel
   • Anisotropic → full momentum-space grid may be needed
   • Discrete symmetries (e.g., valley degeneracy) → block-diagonal structure

3. What is the natural energy variable?

   • Fermi systems: $\xi = (\varepsilon - \mu)/k_BT$ (centered on Fermi surface)
   • Bose systems: $\xi = \hbar\omega/k_BT$ (thermal occupation scale)
   • Classical: $\xi = \varepsilon/k_BT$

4. What weight function defines the inner product?

   • This determines the Hilbert space and the Gram-Schmidt orthogonalization
   • Fermi: $g(\xi) = f^0(1-f^0)$ → peaked at Fermi surface
   • Bose: $g(\xi) = n^0(1+n^0)$ → broad, thermal
   • Classical: $g(\xi) = e^{-\xi}$ → Laguerre-like

5. How many basis functions are needed?

   • Transport coefficients converge fast ($N_b = 6$–$8$ usually sufficient)
   • Eigenvalue spectra need more ($N_b \geq 30$ for structure, $\geq 100$ for power-law fits)
   • Match $N_b$ to the user's requirements from Stage 0b

6. Are there existing implementations that cover this system?

   • Check if boltzmann_transport already has the needed dispersion, interaction, and scattering topology
   • If yes → use it. If no → plan what needs to be added

Output: A brief assessment document addressing these questions, with a recommendation:

• "This is a standard isotropic 2D Fermi system → angular-harmonic + polynomial basis, well supported by the existing code"
• OR "This requires a new dispersion relation (e.g., honeycomb lattice) → need to implement a custom dispersion, but the rest of the pipeline applies"
• OR "This problem is anisotropic → angular harmonics won't decouple, need a full 2D grid approach"

Present to user and discuss. The user may have insight about which basis works best for their system.

Stage B: Theory Document

HARD GATE: Do NOT write any computation code until this document is written and approved.

After understanding the requirements (Stage 0) and basis strategy (Stage A), write a self-contained theoretical derivation document covering the specific calculation to be performed. Save it as a markdown file (e.g., docs/theory_<system_name>.md).

The document must include

1. Problem statement — What system, what we're computing, what approximations
2. Hamiltonian / interaction — Starting microscopic Hamiltonian, matrix elements $|M(q)|^2$
3. Linearization — How the collision integral is linearized around equilibrium, what $\delta f$ represents
4. Collision operator derivation — The specific form of $C[\delta f]$ for this system, with all Fermi/Bose factors, Jacobians, and integration measures written out explicitly
5. Symmetry reduction — How angular decomposition (or other symmetry) reduces the operator, what each angular channel $l$ represents physically
6. Inner product and basis — Write out the inner product definition explicitly, including the weight function, integration measure, and discretization: $$\langle f, h \rangle = \int f(\xi), h(\xi), g(\xi), \rho(\xi), d\xi \approx \sum_{i=1}^{N_q} f(\xi_i), h(\xi_i), g(\xi_i), w_i$$ where $g(\xi)$ is the statistical weight (e.g., $f^0(1-f^0)$ for Fermi), $\rho(\xi)$ is the density of states (absorbed into $w_i$ after quadrature), and $(\xi_i, w_i)$ are quadrature nodes/weights. Then explain how the Gram-Schmidt polynomial basis ${\psi_m(\xi)}$ is built to satisfy $\langle \psi_m, \psi_n \rangle = \delta_{mn}$, and how the continuous collision operator becomes a matrix $C_l[m,n] = \langle \psi_m, C_l \psi_n \rangle$
7. Transport formulas — The specific source vectors $\mathbf{s}$ for each transport coefficient, the Onsager matrix construction, and how final physical quantities are extracted
8. Conservation laws and zero modes — Which quantities are conserved, what zero modes to expect, and how $\tau_{\mathrm{mr}}$ enters
9. Known limits and benchmarks — What the results should reduce to in limiting cases (e.g., low-$T$, high-$T$, free-particle, strong-screening)
10. Key formulas summary — A compact list of all numbered equations needed for implementation

This is a physics document, not a code document. It should read like a methods section of a paper — someone who reads it should understand the full derivation from Hamiltonian to transport coefficient, without needing to read any code.

Present the document to the user for review. Ask:

• "Does the Hamiltonian correctly describe your system?"
• "Are the approximations appropriate for the regime you care about?"
• "Are there additional limiting cases we should check against?"
• "Is anything missing from the derivation?"

Do NOT proceed to Stage C until the user confirms the theory is correct.

Stage C: Coding Plan

After the theory document is approved, write a concrete coding plan. Save it as a markdown file (e.g., docs/plan_<system_name>.md).

The plan must include

1. What already exists — Which parts of boltzmann_transport (or boltzmann_2deg) can be reused as-is
2. What needs to be added or modified — New dispersion, interaction, scattering topology, transport recipe, etc. List each new function/class with its inputs, outputs, and the equation it implements (reference the theory document by equation number)
3. Implementation order — Which pieces to build first and how to test each one incrementally
4. Test strategy — For each new component:
   • Unit test: what input → what expected output (from known limits in the theory document)
   • Integration test: does the assembled pipeline reproduce a benchmark?
   • Convergence test: does the result stabilize as $N_b$ or $n_{\mathrm{quad}}$ increases?
5. Output specification — Exactly which figures, tables, and data files will be produced, matching the user's requirements from Stage 0b
6. Estimated complexity — How many new functions, roughly how many lines, any performance concerns (e.g., large $N_b$ requiring optimized kernel)

Present the plan to the user. Ask:

• "Does this cover everything you wanted?"
• "Is the testing strategy sufficient to give you confidence in the results?"
• "Any concerns about the implementation approach?"

Do NOT begin execution (Stage 1) until the user approves the plan.

EXECUTION PHASE (Stages 1–8)

Now proceed with the computation, following the approved theory document and coding plan.

Stage 1: Define the System

Discuss with the user to determine the five choices:

Plus parameters: coupling $r_s$, degeneracy $T/T_F$, momentum relaxation $\tau_{\mathrm{mr}}^{-1}$.

Output: Summary table of all choices. Explain what regime the parameters put us in (e.g., "at $T/T_F = 0.05$, the system is strongly degenerate — only states within $5%$ of the Fermi energy participate in scattering").

Stage 2: Natural Units

Explain why we nondimensionalize and present the chosen scales:

Output: Derived dimensionless parameters with physical meaning:

• "$\mu/k_BT = 20$ means the chemical potential is 20 thermal widths above the band bottom — a sharp Fermi surface"
• "$q_{\mathrm{TF}}/k_F = 2$ means the screening length is half the Fermi wavelength — screening is strong at long wavelengths"

Point out what the user should check: Are the derived parameters physically reasonable for their material/experiment?

Stage 3: Equilibrium and Weight Function

Compute and plot $f^0(\xi)$ and $g(\xi)$. Explain what $g(\xi)$ physically means:

• For Fermi: $g = f^0(1-f^0)$ requires both an occupied initial state AND an empty final state → scattering only near the Fermi surface
• For Bose: $g = n^0(1+n^0)$ has Bose enhancement → scattering strongest where occupation is high
• For Classical: $g = e^{-\xi}$ → scattering weighted toward low energies

Output:

• Plot of $f^0(\xi)$ and $g(\xi)$ with axis labels and physical interpretation
• "The weight function is concentrated in the range $|\xi| \lesssim 5$, so only states within $\sim 5 k_BT$ of $\mu$ contribute to transport"
• Save plot data as .txt
• What to verify: Does the width of $g(\xi)$ match expectations? For a metal at 300K with $T_F \sim 50{,}000$K, the active shell is $\sim 0.006%$ of the band width.

Stage 4: Symmetry Analysis and Basis Selection

Explain the symmetry analysis and why the basis choice matters:

Output:

• Symmetry analysis: "The parabolic dispersion $\varepsilon = k^2$ depends only on $|k|$, so the system has full rotational symmetry. This means angular channel $l$ decouples from $l'$."
• Conservation laws: "e-e normal scattering conserves momentum, so $l=1$ will have one zero mode. If we add impurity scattering, this zero mode is lifted."
• Recommended basis with reasoning and any alternatives considered
• Resolution parameters ($N_b$, $n_{\mathrm{quad}}$, etc.) with explanation of what they control
• What to verify: Is $N_b$ large enough? "Transport typically converges by $N_b = 6\text{--}8$; eigenvalue spectra need $N_b \geq 30$."

Stage 5: Collision Kernel Construction

Build the collision matrix $C_l$ using the outer-product construction:

$$C_l \mathrel{+}= P_e \cdot \mathbf{c}_e \mathbf{c}_e^T$$

By topology:

Critical implementation detail: Use plain $\psi$ (NOT $\psi \cdot gw$) for basis projection. Explain why: "The $gw$ factor is already part of the inner product definition $\langle f, h \rangle = \sum f_i h_i g_i w_i$. Including it in the sign vector would double-count it, giving eigenvalues that are too small by a factor of $\sim gw^2$."

Output:

• Computation time and matrix dimensions
• Matrix element distribution: heatmap of $|C_l[m,n]|$ + histogram
• Explain the checkerboard pattern (if present): "Even-index basis functions are even in $\xi$, odd-index are odd. The collision operator preserves parity, so even-odd matrix elements vanish."
• Explain the diagonal dominance: "Diagonal elements $C_l[n,n] = \langle\psi_n|C|\psi_n\rangle \geq 0$ (positive semidefiniteness). They represent the self-relaxation rate of mode $n$."
• Save matrix data as .txt
• What to verify: Are the matrix elements of reasonable magnitude? Do they grow with $n$ (higher modes relax faster)?

Stage 6: Diagnostics (MANDATORY — HARD GATE)

Run ALL checks and explain what each one tests and why it matters:

Output:

• Full diagnostics table with PASS/FAIL, numerical values, and physical interpretation of each
• "Symmetry holds to $10^{-15}$ — this is exact by the outer-product construction, not a coincidence"
• "The smallest eigenvalue in $l=0$ is $10^{-13}$, separated from the first positive eigenvalue by 11 orders of magnitude — conservation laws are extremely well satisfied"
• If ANY check fails: explain what is physically wrong, what likely caused it (insufficient quadrature? bug in kinematics?), and how to fix it. Do NOT proceed.
• What to verify: The user should check that the zero-mode count matches the conservation laws of their specific scattering channels.

Stage 7: Transport Coefficients

Explain the physics of the transport solve:

"We solve $(C_1 + \tau_{\mathrm{mr}}^{-1} I), \mathbf{a} = \mathbf{s}$ — this is the steady-state balance between the external driving force ($\mathbf{s}$) and the combined relaxation from e-e collisions ($C_1$) plus momentum relaxation ($\tau_{\mathrm{mr}}^{-1}$)."

Output:

• Transport coefficient table with exact values (and RTA values if requested)
• Onsager matrix $L_{ab}$ if computing thermoelectric coefficients
• Onsager reciprocity check: $L_{12} = L_{21}$ must hold; any deviation indicates a numerical error
• If the user requested RTA comparison: compute RTA values and present the exact/RTA ratio. Do NOT interpret why the RTA succeeds or fails — present the numbers and discuss with the user what they mean for their specific system.
• Save all values as .txt
• What to verify: Is $\sigma > 0$? Is $\kappa > 0$? Do the transport coefficients match known limits or literature values for this system?

Stage 8: Eigenmode Analysis

Output the numerical results. Do NOT provide pre-baked interpretations. Present the data clearly and discuss with the user what the results mean for their system.

Output:

1. Complete eigenvalue table — all eigenvalues sorted, with classification (zero/slow/fast)

2. Eigenvalue histogram — show the distribution of eigenvalues

3. Log-log plot of $\lambda_n$ vs $n$ — fit a power law if the data supports it; if the fit is poor, say so

4. Mode-resolved transport — bar chart showing each mode's contribution to each transport coefficient the user requested

5. Eigenvector structure — plot representative eigenstates (e.g., slowest and fastest)

6. Save ALL data as .txt files

After presenting the data, discuss with the user:

• Do the eigenvalue counts (zero modes, etc.) match the conservation laws expected for this system?
• Is the eigenvalue distribution what the user expects? If anything looks surprising, flag it and ask.
• Which modes dominate transport? Let the user draw conclusions about their system.

Do NOT make blanket claims about RTA validity, power-law exponents, or mode dominance patterns. These depend on the specific system and must be verified case by case with the user.

Code: Using boltzmann_transport

Codebase location: ~/Desktop/Github/boltzmann_transport/

from boltzmann_transport import SystemConfig, BoltzmannSolver

system = SystemConfig(
    dimension=2,                    # 1, 2, or 3
    dispersion="parabolic",         # or "dirac", "acoustic_phonon", custom callable
    statistics="fermi",             # or "bose", "classical"
    interaction="coulomb_tf",       # or "contact", "coulomb_3d", custom callable
    scattering=["ee_normal"],       # or ["impurity"], ["phonon_3body_merge"]
    params={"r_s": 1.0, "T_over_TF": 0.05},
    tau_mr_inv=0.01,
)

solver = BoltzmannSolver(system)
result = solver.run(recipe="thermoelectric")  # or "phonon_thermal"

# Access results
result.transport["sigma"]            # electrical conductivity
result.transport["kappa"]            # thermal conductivity
result.transport["sigma_ratio_rta"]  # exact/RTA ratio
result.eigenmodes[1].eigenvalues     # l=1 eigenvalue spectrum

Basis advisor (automated basis selection):

result = solver.run(auto_advise=True)
print(result.basis_recommendation.reasoning)

Common Mistakes

Reference Documentation