Doublet Streamline Model Physics Knowledge
This skill provides physics knowledge for the 2-D doublet (injection-production well pair) model using streamline methods. The model solves advection-reaction-dispersion problems along circular streamlines in a potential flow field.
When This Skill Applies
- Modifying streamline geometry calculations (bipolar coordinates)
- Changing transport solvers (hydrodynamic, chemical, thermal)
- Implementing or modifying breakthrough curve integration
- Working with Green's function kernels for thermal transport
- Debugging unexpected breakthrough behavior
- Planning changes to physics-related code
- Explaining why the model behaves a certain way
Core Physics Reference
The model tracks transport in a 2-D potential flow field between an injector (+a, 0) and producer (-a, 0):
| Module | Transport Type | Solution Method |
|---|---|---|
| Hydrodynamic | Pure advection | Time-of-flight along streamlines |
| Chemical | Advection + capacity-limited reaction | Logistic traveling wave |
| Thermal | Advection + fluid-matrix exchange | Bessel-function Green's kernel |
Key state variables:
| Variable | Symbol | Meaning | Units |
|---|---|---|---|
| Take-off angle | β | Angle at which streamline leaves injector | rad |
| Time-of-flight | τ(β) | Travel time from injector to producer | s |
| Arc position | φ | Angle along circular streamline | rad |
| Concentration | C(φ,t) | Solute mass fraction | kg/kg |
| Capacity | S(φ,t) | Remaining reaction capacity | kg/kg |
| Fluid temperature | Tf(φ,t) | Fluid temperature along streamline | °C |
| Matrix temperature | Tm(φ,t) | Rock matrix temperature | °C |
For detailed equations, see EQUATIONS.md. For symbol definitions and units, see SYMBOLS.md. For derivation logic, see DERIVATIONS.md. For edge cases and sanity checks, see SANITY_CHECKS.md.
Workflow A: Physics Validation
Use this workflow when reviewing or planning code changes.
Step 1: Identify affected transport type
Determine which transport physics is affected:
- Hydrodynamic: Streamline geometry, time-of-flight, velocity field
- Chemical: Capacity-limited reaction, logistic traveling wave
- Thermal: Fluid-matrix exchange, Bessel function kernel
Step 2: Check coordinate system consistency
The model uses multiple coordinate systems:
- Cartesian (x, y) for plotting
- Bipolar (ξ, β) for streamline parameterization
- Polar about streamline center (R, φ) for local calculations
Verify transformations are applied correctly.
Step 3: Verify breakthrough integration
Breakthrough curves integrate over all streamlines:
C_prod(t) = (1/π) ∫_0^π C(β, t) dβ
Check that:
- Integration weights are correct (trapezoidal or custom)
- β limits span [0, π] (or arrived streamlines only)
- Singularities at β → 0, π are handled
Step 4: Check Green's function stability (thermal)
For thermal transport, the Bessel kernel G(τ, t) can overflow:
- Verify exponent recentering is applied
- Check that i1e (scaled Bessel I1) is used instead of i1
- Verify prefix integrals use cumulative_trapezoid
Step 5: Report findings
Summarize:
- Which transport type is affected
- Any coordinate transformation issues
- Any integration boundary issues
- Any numerical stability concerns
- Recommendations for correction
Workflow B: Physics Reasoning
Use this workflow when explaining behavior, debugging, or proposing solutions.
For explaining physics concepts:
- Identify the relevant equations and parameters
- State the physical interpretation
- Explain cause-and-effect relationships
- Use the derivation steps from DERIVATIONS.md to show connections
For debugging simulation issues:
- Identify which transport type shows unexpected behavior
- Check if the issue relates to:
- Breakthrough timing (τ calculation)
- Front retardation (reaction capacity)
- Thermal lag (fluid-matrix exchange rates)
- Trace through the analytical solution
- Check edge cases against SANITY_CHECKS.md
For proposing physics-consistent changes:
- Identify which equations are affected
- Show how new terms integrate into the transport equations
- Demonstrate that mass/energy balance is preserved
- Identify any new sanity checks needed
Quick Reference: Module Structure
| Module | Purpose | Key Functions |
|---|---|---|
doublet.py | Main model (streamlines, chemical, thermal) | Tf, Ctf, Cxf, Ttf, Txf, breakthrough |
streamlines.py | Bipolar coordinate streamlines | streamline_bipolar, streamtube_width |
diffusion.py | Green's kernel solver with diffusion | solve_kernel_capacity, cxfD, ctDf |
thermal.py | Thermal kernel (alternative impl.) | thermal_kernel_Tf_Tm_xvec_t |
thermal2.py | Optimized thermal solver | G_grid_efficient, run_breakthrough, Tprodf |
notebook_widgets.py | Interactive Jupyter visualizations | visualize_* functions |
Key Physical Constraints
These must always hold:
- Streamline geometry: Streamlines are circular arcs through (±a, 0)
- Travel time bounds: T(β=0) = 4πna²/(3Q) is minimum arrival time
- Velocity singularity: v → ∞ at wells (handled by coordinate transformation)
- Conservation: Integrated flux across all streamlines equals Q
- Retardation: Chemical front travels at speed v·C_inj/(C_inj + S_0)
- Thermal equilibrium: As t → ∞, Tf → Tm → T_inj (behind the front)
Transport Type Classification
| Transport | Governing Equation | Solution Type |
|---|---|---|
| Hydrodynamic | ∂C/∂t + v·∇C = 0 | Method of characteristics |
| Chemical (no diffusion) | ∂C/∂t + v·∇C = -kCS | Logistic traveling wave |
| Chemical (with diffusion) | ∂C/∂t + v·∇C = D∇²C - kCS | Green's function convolution |
| Thermal | ∂Tf/∂t + v·∇Tf = -γ(Tf - Tm) | Bessel kernel (Eq. 47) |
| Matrix | ∂Tm/∂t = β(Tf - Tm) | Exponential convolution (Eq. 48) |
Dimensionless Groups
| Group | Definition | Physical Meaning |
|---|---|---|
| Retardation R | (C_inj + S_0)/C_inj | Front slowdown factor |
| Damköhler Da | k·τ | Reaction extent over travel time |
| Péclet Pe | v·L/D | Advection vs diffusion |
| β·τ | (exchange rate)·(travel time) | Matrix equilibration extent |
| γ·τ | (exchange rate)·(travel time) | Fluid cooling extent |
