Troubleshooting Guide

Overview

This comprehensive troubleshooting guide helps diagnose and resolve common issues encountered when modeling wastewater treatment plants in ErgoPlanner. Each problem includes symptoms, likely causes, diagnostic steps, and solutions.

How to Use This Guide:

1. Identify your problem category from the table of contents
2. Review symptoms to confirm the issue
3. Follow diagnostic steps systematically
4. Apply recommended solutions
5. Verify the fix worked

Quick Reference: Use Ctrl+F (Cmd+F on Mac) to search for specific error messages or symptoms.

---

Table of Contents

1. Simulation Errors
2. Convergence Problems
3. Mass Balance Issues
4. Unrealistic Results
5. Performance Problems
6. Nitrification Issues
7. Denitrification Problems
8. Phosphorus Removal Issues
9. Settling and Clarification
10. Data Import/Export Issues

---

1. Simulation Errors

1.1 "Simulation Failed to Start"

Symptoms:

• Error message when clicking "Run Simulation"
• Simulation never begins
• No results generated

Likely Causes:

☐ Missing required input data (flow, concentrations)
☐ Invalid process configuration (disconnected units)
☐ Unit conversion errors
☐ Negative or zero values in critical parameters
☐ Insufficient memory

Diagnostic Steps:

Step 1: Check Input Data Completeness
- Navigate to: Simulation → Input Review
- Verify all required fields have values:
  ☑ Influent flow
  ☑ Temperature
  ☑ All concentrations (BOD/COD, TKN, TP, TSS)

Step 2: Verify Process Configuration
- View: Model → Process Flow Diagram
- Ensure all units connected properly
- Check for orphaned units (no inlet/outlet)

Step 3: Review Parameter Values
- Settings → Parameters → Check All
- Look for:
  ✗ Negative values
  ✗ Zero values in denominators
  ✗ Extremely large values (>1e6)

Step 4: Check Error Log
- Help → View Error Log
- Read detailed error message
- Look for specific parameter or unit mentioned

Solutions:

Solution 1: Complete Missing Data
- Fill in all required influent parameters
- Use measured data or reasonable estimates
- Set minimum values for zero entries

Solution 2: Fix Process Configuration
- Reconnect disconnected units
- Remove orphaned equipment
- Verify flow path from influent to effluent

Solution 3: Correct Invalid Parameters
- Replace negative values with positive
- Set minimums for zero values (e.g., temp > 5°C)
- Check units match (MGD vs m³/day)

Solution 4: Reduce Model Complexity
- Simplify if memory insufficient
- Split into multiple simulations
- Use reduced timestep count

Example Fix:

Error: "Influent temperature must be > 0°C"

Cause: Temperature field left at default 0
Fix: Set temperature to measured value (e.g., 18°C)
Result: Simulation starts successfully ✓

---

1.2 "Integration Error at Time = X"

Symptoms:

• Simulation runs for some time, then crashes
• Error mentions specific timestamp
• Partial results available

Likely Causes:

☐ Time step too large for dynamics
☐ Sudden input change (shock load)
☐ Numerical stiffness
☐ Parameter values outside valid range
☐ Division by zero in calculations

Diagnostic Steps:

Step 1: Identify Problem Timestep
- Note time of failure from error message
- Check what happens at that time:
  • Input data changes suddenly?
  • Equipment starts/stops?
  • Control action triggered?

Step 2: Review Input Data at Failure Point
- Data → View Time Series
- Look for:
  ✗ Spikes or jumps in influent
  ✗ Missing data (replaced with zeros?)
  ✗ Unrealistic values

Step 3: Check Intermediate Results
- Results → View Partial Results
- Examine state variables just before crash:
  • DO going negative?
  • Concentrations approaching zero?
  • MLSS becoming unrealistic?

Solutions:

Solution 1: Reduce Time Step
Current: 1 hour → Try: 15 minutes
- Simulation → Settings → Time Step
- Reduce by factor of 2-4
- Re-run simulation

Solution 2: Smooth Input Data
- Data → Preprocessing → Moving Average
- Apply 3-point or 5-point smoothing
- Removes sudden spikes

Solution 3: Adjust Solver Settings
- Simulation → Advanced → Solver Options
- Reduce absolute tolerance (1e-6 → 1e-8)
- Reduce relative tolerance (1e-4 → 1e-6)
- Try different solver (e.g., Rosenbrock → BDF)

Solution 4: Add Input Data Constraints
- Data → Validation → Set Limits
- Cap maximum values (e.g., BOD < 1000 mg/L)
- Set minimum values (e.g., DO > 0 mg/L)

Example Fix:

Error: "Integration error at t = 156.5 hours"

Diagnosis:
- Checked data at t = 156.5 hr
- Found influent BOD spike: 200 → 2000 mg/L (typo: extra zero)

Fix:
- Corrected BOD data point: 2000 → 200 mg/L
- Re-ran simulation

Result: Completed successfully ✓

---

2. Convergence Problems

2.1 "Model Did Not Converge"

Symptoms:

• Simulation completes but reports non-convergence
• Results may be inaccurate
• Warning messages about iterations

Likely Causes:

☐ Insufficient iterations
☐ Poor initial conditions
☐ Conflicting constraints
☐ Parameters outside stable range
☐ Process configuration incompatible

Diagnostic Steps:

Step 1: Check Convergence Criteria
- Results → Convergence Report
- Review:
  • Maximum residual value
  • Number of iterations used
  • Which variables didn't converge

Step 2: Examine Iteration History
- Results → Advanced → Iteration Log
- Look for:
  • Oscillating values
  • Monotonic increase/decrease
  • Plateauing before convergence

Step 3: Review Initial Conditions
- Simulation → Initial Conditions
- Check if starting values reasonable:
  • MLSS: 2000-5000 mg/L (typical)
  • DO: 1-3 mg/L (aerobic zones)
  • TSS in clarifier: 2000-8000 mg/L

Solutions:

Solution 1: Increase Iteration Limit
- Simulation → Settings → Max Iterations
- Increase from 100 to 500
- Or set to "Auto" (adaptive)

Solution 2: Improve Initial Conditions
- Use steady-state pre-run:
  1. Simulation → Pre-Run → Steady State
  2. Let model reach equilibrium
  3. Use resulting state as initial condition

Solution 3: Relax Convergence Tolerance
- Advanced → Convergence Settings
- Increase tolerance (1e-6 → 1e-5)
- Balance accuracy vs. convergence
- Only if tight tolerance not critical

Solution 4: Use Successive Relaxation
- Advanced → Enable Under-Relaxation
- Relaxation factor: 0.5-0.8
- Slows convergence but improves stability

Solution 5: Simplify Model
- Remove minor units temporarily
- Use simplified kinetics
- Add complexity gradually

Example Fix:

Warning: "Nitrate concentration did not converge (residual = 0.015 mg/L)"

Diagnosis:
- Convergence criteria set very tight (1e-7)
- Nitrate oscillating between 4.82 and 4.84 mg/L
- Practically converged, but not meeting criteria

Fix:
- Relaxed convergence tolerance to 1e-5
- Residual now 0.015 is acceptable (< 1e-5 relative to ~5 mg/L)

Result: Model converges, results essentially unchanged ✓

---

2.2 "Steady-State Not Reached"

Symptoms:

• Long simulation time
• State variables still changing at end
• No clear steady-state in results

Likely Causes:

☐ Simulation duration too short
☐ System has long time constant (high SRT)
☐ Oscillatory behavior (control loops)
☐ Limit cycle (no true steady-state)
☐ External disturbances prevent equilibrium

Diagnostic Steps:

Step 1: Plot State Variables vs. Time
- Results → Plots → Time Series
- Check MLSS, NH4, NO3, etc.
- Look for:
  • Still trending (not flat)
  • Oscillations
  • Slow drift

Step 2: Calculate System Time Constant
- Dominant time constant ≈ SRT for biological systems
- Rule of thumb: Run 3-5× SRT
- Example: SRT = 15 days → run 45-75 days

Step 3: Check for Disturbances
- Data → Influent → Plot
- Verify steady influent (not varying)
- Check controls not cycling

Solutions:

Solution 1: Extend Simulation Duration
- Current: 30 days → Try: 90 days
- Especially for long SRT systems (>15 days)
- Allow 3-5× SRT for equilibrium

Solution 2: Use Accelerated Steady-State Solver
- Simulation → Steady-State Mode
- Bypasses dynamics, finds equilibrium directly
- Much faster than dynamic simulation

Solution 3: Dampen Oscillations
- If control loops causing oscillations:
  • Increase controller dead-band
  • Reduce controller gain
  • Add low-pass filter to measurements

Solution 4: Accept Quasi-Steady-State
- If small oscillations remain:
  • Use time-averaged values
  • Ensure mean is stable
  • Document variability

Example Fix:

Issue: MLSS still increasing after 30-day simulation

Diagnosis:
- SRT = 20 days (long)
- MLSS trend: still slowly rising
- Need longer simulation

Fix:
- Extended simulation to 100 days (5× SRT)
- MLSS stabilized by day 75

Result: Clear steady-state reached ✓

---

3. Mass Balance Issues

3.1 "COD Balance Error > 10%"

Symptoms:

• Mass balance check fails
• COD in ≠ COD out + COD wasted + COD respired
• Warning message about mass balance

Likely Causes:

☐ Missing waste stream
☐ Incorrect recycle configuration
☐ Influent fractionation errors
☐ Stoichiometry modified incorrectly
☐ Data entry errors

Diagnostic Steps:

Step 1: Review Mass Balance Report
- Results → Mass Balance → COD
- Compare:
  • COD In (influent)
  • COD Out (effluent + waste)
  • COD Destroyed (respiration)
  • Error percentage

Step 2: Check All Streams
- Model → Streams → List All
- Verify:
  ☑ Influent stream defined
  ☑ Effluent stream defined
  ☑ WAS stream included
  ☑ All recycles properly connected

Step 3: Verify COD Fractionation
- Data → Influent → COD Fractions
- Check sum = 100%:
  SI + SS + XS + XI = 1.0

Step 4: Review Stoichiometric Coefficients
- Parameters → Stoichiometry
- Ensure defaults not changed (unless intentional)

Solutions:

Solution 1: Add Missing Waste Stream
- Common mistake: WAS not included
- Model → Streams → Add Waste Stream
- Connect to appropriate point

Solution 2: Fix Recycle Flows
- Check recycle ratios match facility
- Verify recycle streams in mass balance
- Common issue: RAS flow incorrect

Solution 3: Correct Influent Fractionation
Example error:
  SI = 0.10
  SS = 0.30
  XS = 0.45
  XI = 0.20
  Total = 1.05 ✗ (should be 1.00)

Fix: Normalize fractions:
  SI = 0.10/1.05 = 0.095
  SS = 0.30/1.05 = 0.286
  XS = 0.45/1.05 = 0.429
  XI = 0.20/1.05 = 0.190
  Total = 1.000 ✓

Solution 4: Reset Stoichiometry
- If coefficients changed accidentally:
- Parameters → Stoichiometry → Restore Defaults

Example Fix:

Error: COD Balance Error = +15%

Mass Balance:
- COD In: 10,000 kg/day
- COD Out (effluent): 750 kg/day
- COD Wasted (WAS): 1,200 kg/day
- COD Destroyed: 6,950 kg/day
- Total Out: 8,900 kg/day
- Missing: 1,100 kg/day (11%)

Diagnosis:
- Checked process configuration
- Found recycle from clarifier to headworks not included in balance

Fix:
- Added recycle stream to mass balance calculations
- Verified recycle flow = 200% of influent

Result: COD Balance Error = 2.1% ✓ (acceptable)

---

3.2 "Nitrogen Balance Error"

Symptoms:

• TN in ≠ TN out + TN wasted + TN denitrified
• Nitrogen appearing or disappearing

Likely Causes:

☐ Denitrification not accounted for
☐ Nitrification stoichiometry issues
☐ Nitrogen in biomass not tracked correctly
☐ Missing N2 gas release
☐ Incorrect TKN fractionation

Diagnostic Steps:

Step 1: Review N Balance Report
- Results → Mass Balance → Nitrogen
- Check all pathways:
  • NH4-N in influent
  • Organic N in influent
  • NO3-N in effluent
  • N in waste sludge
  • N denitrified (to N2 gas)

Step 2: Calculate Expected Denitrification
- N nitrified = Influent TKN - Effluent TKN - N in WAS
- N to effluent = NH4 + NO3 + Organic N (typically small)
- N denitrified = N nitrified - NO3 in effluent

Step 3: Verify N in Biomass
- N content of biomass typically 11-14% of VSS
- WAS N = WAS VSS × 0.12 (typical)
- Check this matches model calculation

Solutions:

Solution 1: Include Denitrification
- Ensure anoxic zones configured
- Verify denitrification enabled
- Check N2 gas release tracked

Solution 2: Check Biomass N Content
- Parameters → Biomass Composition
- Verify iNBM (N content of biomass)
  Default: 0.07 g N/g COD biomass
  Or 0.10-0.14 g N/g VSS

Solution 3: Verify TKN Fractionation
- Influent TKN = NH4-N + Organic N
- Organic N = Soluble + Particulate
- Fractions should sum to TKN

Solution 4: Check Stoichiometry
- Nitrification: 1 g NH4-N → 1 g NO3-N (correct)
- Denitrification: 1 g NO3-N → 0.5 g N2 (correct)
- Verify these ratios in model

Example Fix:

Error: N Balance showing 25% excess nitrogen (appearing from nowhere)

Diagnosis:
- Reviewed mass balance details
- Found denitrification being counted twice:
  • Once as NO3 removal
  • Once as N2 release
- Double-counting!

Fix:
- Corrected mass balance calculation logic
- N2 gas derived from NO3 reduction, not independent

Result: N Balance Error = 3.5% ✓ (acceptable)

---

4. Unrealistic Results

4.1 "Negative Concentrations"

Symptoms:

• Negative values for DO, NH4, NO3, etc.
• Physically impossible results
• May cause simulation to crash

Likely Causes:

☐ Numerical instability
☐ Time step too large
☐ Consumption rate > production rate
☐ Solver tolerance too loose
☐ Parameters outside valid range

Diagnostic Steps:

Step 1: Identify Negative Variables
- Results → Review All Variables
- Note which parameters go negative
- Check when it first occurs

Step 2: Review Consumption/Production
- For variable going negative, check:
  • What processes consume it?
  • What processes produce it?
  • Is consumption exceeding production?

Step 3: Check Model Configuration
- Verify proper aeration (for DO)
- Verify recycle flows (for NO3)
- Check for disconnected zones

Solutions:

Solution 1: Reduce Time Step
- Smaller time step improves accuracy
- Try: 1 hr → 15 min → 5 min
- Until negative values eliminated

Solution 2: Apply Non-Negativity Constraints
- Simulation → Settings → Apply Constraints
- Enable "Force Non-Negative Concentrations"
- Model clips values at zero

Solution 3: Adjust Process Rates
- If consumption too fast:
  • Reduce kinetic rate constants
  • Check parameters within literature range
  • Verify temperature correction factors

Solution 4: Fix Configuration Issues
- DO negative? Check aerator capacity
- NH4 negative? Check nitrification rate
- Substrate negative? Check influent loading

Example Fix:

Issue: DO going negative in aerobic zone

Diagnosis:
- DO drops below zero during peak load
- Oxygen consumption > aeration capacity
- Time step = 1 hour (too large to capture dynamics)

Fix Applied:
1. Reduced time step to 15 minutes
2. Increased aerator capacity to match OUR
3. Applied non-negativity constraint as safety

Result: DO stays positive, realistic values (1.5-2.5 mg/L) ✓

---

4.2 "Effluent Better Than Influent"

Symptoms:

• Effluent concentration higher than influent
• Example: Effluent TP > Influent TP
• Violates physical reality

Likely Causes:

☐ Recycle stream configuration error
☐ Units confusion (mg/L vs kg/day)
☐ Flow balance incorrect
☐ P release from biomass (if TP)
☐ Process configuration backwards

Diagnostic Steps:

Step 1: Compare Concentrations vs. Loads
- Concentration: mg/L (can increase if flow decreases)
- Load: kg/day (should never increase)
- Check both

Step 2: Verify Flow Balance
- Effluent flow should ≈ Influent flow - WAS flow
- Check for flow multiplication errors

Step 3: Review Process Flow
- Model → Flow Diagram → Trace Flow
- Ensure flow direction correct
- Check for circular recycles

Step 4: Check Units
- Data → Units → Verify All
- Ensure consistent units throughout

Solutions:

Solution 1: Fix Recycle Configuration
- Check RAS, WAS, and internal recycles
- Verify flow directions correct
- Ensure recycles not creating net addition

Solution 2: Correct Unit Conversions
- Review all data import
- Verify flow units (MGD vs m³/day)
- Check concentration units (mg/L vs g/m³)

Solution 3: Fix Flow Balance
Example error:
  Influent: 10 MGD, TP = 6 mg/L → 500 kg/day
  WAS: 0.05 MGD, TP = 60 mg/L → 25 kg/day
  Effluent: 10 MGD, TP = 8 mg/L → 668 kg/day ✗

This violates mass balance! Issue likely in flow or concentration data.

Solution 4: Check P Release (if applicable)
- Under anaerobic conditions, PAOs release P
- This can temporarily increase TP in stream
- Check if anaerobic zone before sampling point
- Ensure sample location matches model point

Example Fix:

Issue: Model shows effluent TP = 8 mg/L, influent TP = 6 mg/L

Diagnosis:
- Checked flow balance: OK
- Checked mass balance: Failed (P appearing)
- Found: RAS recycle accidentally set to 10× instead of 1× flow
- Error multiplying P return to plant

Fix:
- Corrected RAS flow: 10.0 MGD → 7.5 MGD (75% of influent)
- Result: Effluent TP = 0.9 mg/L ✓ (realistic)

---

5. Performance Problems

5.1 "Simulation Too Slow"

Symptoms:

• Simulation takes hours to complete
• Progress bar barely moving
• CPU usage high

Likely Causes:

☐ Time step too small
☐ Model too complex
☐ Long simulation duration
☐ Inefficient solver settings
☐ Memory swapping

Diagnostic Steps:

Step 1: Identify Bottleneck
- Monitor → Performance
- Check:
  • Time per simulation step
  • Which process unit slowest
  • Memory usage

Step 2: Review Simulation Settings
- Check:
  • Time step (smaller = slower)
  • Duration (longer = slower)
  • Output frequency (more often = slower)

Step 3: Check System Resources
- Task Manager / Activity Monitor
- Verify:
  • CPU usage
  • Memory available
  • Disk I/O (if swapping)

Solutions:

Solution 1: Increase Time Step
- If dynamics not critical:
  Current: 5 min → Try: 15 min or 1 hr
- Reduces calculation points
- Trade-off: accuracy vs. speed

Solution 2: Simplify Model
- Remove minor units
- Use simplified kinetics (e.g., ASM1 vs ASM3)
- Reduce spatial resolution (fewer zones)

Solution 3: Optimize Solver Settings
- Simulation → Advanced → Solver
- Try different solvers:
  • Euler (fastest, least accurate)
  • Runge-Kutta 4 (moderate)
  • BDF (for stiff systems)
- Increase tolerances slightly

Solution 4: Reduce Output Frequency
- Results → Output Settings
- Save data every hour instead of every time step
- Doesn't affect calculation, just storage

Solution 5: Use Steady-State Where Possible
- If only steady results needed:
- Simulation → Mode → Steady-State
- Bypasses dynamic simulation (much faster)

Solution 6: Upgrade Hardware
- More RAM reduces swapping
- Faster CPU reduces simulation time
- SSD improves I/O performance

Performance Benchmarks:

Typical Simulation Times (desktop computer):

Steady-State:
- Simple AS: 10-30 seconds
- BNR: 30-60 seconds
- Complex multi-train: 1-3 minutes

Dynamic (1 year, hourly timestep):
- Simple AS: 5-10 minutes
- BNR: 10-20 minutes
- Complex multi-train: 30-60 minutes

If significantly slower, optimization needed.

Example Fix:

Issue: 1-year dynamic simulation taking 6 hours

Diagnosis:
- Time step: 1 minute (very small)
- Total steps: 525,600 (365 days × 24 hr × 60 min)
- Output every step: Writing 525,600 data points

Fix:
1. Increased time step to 15 minutes (still adequate for dynamics)
2. Output every hour (not every step)
3. Switched to RK4 solver (faster for this case)

Result: Simulation time reduced to 25 minutes ✓ (14× speedup)

---

6. Nitrification Issues

6.1 "Poor Nitrification (High Effluent NH4)"

Symptoms:

• Model predicts high effluent NH4 (> 2 mg/L)
• Facility achieves better nitrification
• Model under-predicts removal

Likely Causes:

☐ Temperature too low
☐ DO too low
☐ SRT too short
☐ Autotrophic growth rate too low
☐ Inhibition factors incorrect
☐ Alkalinity limitation

Diagnostic Steps:

Step 1: Check Nitrification Fundamentals
Required conditions:
☑ DO > 1.5 mg/L (preferably > 2.0)
☑ Temperature > 10°C (warmer better)
☑ SRT > minimum for nitrifier growth
☑ Alkalinity > 50 mg/L as CaCO3
☑ pH = 7-8 (optimal)

Step 2: Calculate Minimum SRT
SRT_min = 1 / (μA - bA)

At 20°C with defaults:
μA = 0.9 d⁻¹, bA = 0.17 d⁻¹
SRT_min = 1 / (0.9 - 0.17) = 1.37 days

Apply safety factor (1.5-2.5×):
SRT_design > 1.37 × 2.0 = 2.7 days

At 12°C (winter):
μA(12°C) = 0.9 × 1.11^(12-20) = 0.42 d⁻¹
SRT_min = 1 / (0.42 - 0.13) = 3.4 days
SRT_design > 6.8 days

Step 3: Review Autotrophic Parameters
- Parameters → Biological → Autotrophs
- Check:
  • μA,max: typical 0.5-1.5 d⁻¹ at 20°C
  • KNH: typical 0.5-2.0 mg N/L
  • bA: typical 0.10-0.30 d⁻¹

Solutions:

Solution 1: Increase DO Setpoint
- If model DO < 2.0 mg/L:
- Increase to 2.0-2.5 mg/L in aerobic zone
- Verify aeration capacity sufficient

Solution 2: Increase SRT
- If SRT marginal (< 2× minimum):
- Reduce WAS flow
- Increase SRT to 10-15 days (typical for BNR)

Solution 3: Adjust Autotrophic Growth Rate
- If facility nitrifies better than model:
- Calibrate μA to match observations
- Typical adjustment: 0.9 → 1.0 to 1.2 d⁻¹

Solution 4: Check Temperature
- Verify temperature data correct
- Use actual wastewater temp (not air temp)
- Remember: WW temp ≈ Air temp × 0.7 + 10°C (approx)

Solution 5: Verify Alkalinity Sufficient
- Nitrification consumes alkalinity:
  7.14 g alkalinity / g NH4-N oxidized
- Check alkalinity doesn't deplete:
  Alkalinity > 50 mg/L as CaCO3 (minimum)

Example Fix:

Issue: Model predicts NH4 = 3.5 mg/L, actual = 0.5 mg/L

Diagnosis:
- Temperature: 18°C ✓
- DO: 2.2 mg/L ✓
- SRT: 12 days ✓ (adequate)
- μA: 0.9 d⁻¹ (default)
- Checked facility: warm influent from industrial source

Fix:
- Calibrated μA: 0.9 → 1.1 d⁻¹
- Reflects better nitrification at this facility

Result: Model NH4 = 0.6 mg/L ✓ (matches measured)

---

6.2 "Nitrification Unstable / Oscillating"

Symptoms:

• Nitrification performance oscillates
• NH4 alternates between low and high
• Unstable steady-state

Likely Causes:

☐ DO control oscillations
☐ SRT close to minimum (marginal stability)
☐ Temperature fluctuations
☐ Loading variations
☐ Numerical issues (time step)

Diagnostic Steps:

Step 1: Plot NH4 vs. Time
- Results → Time Series → NH4
- Check period of oscillations:
  • Daily (diurnal) variation?
  • Weekly pattern?
  • Random / chaotic?

Step 2: Check DO Control
- Plot DO vs. Time
- Look for:
  • DO oscillations matching NH4 oscillations
  • Controller cycling on/off
  • Insufficient control authority

Step 3: Review SRT Margin
- Calculate SRT / SRT_min ratio
- If < 2.0: Marginal stability
- Small perturbations cause large swings

Solutions:

Solution 1: Dampen DO Control
- Increase controller dead-band
- Reduce controller gain (slower response)
- Add measurement filtering

Solution 2: Increase SRT Safety Margin
- If SRT close to minimum:
- Increase SRT by 20-50%
- Provides buffer against perturbations

Solution 3: Smooth Influent Loading
- If shock loads causing upsets:
- Add equalization basin
- Use flow-paced loading
- Implement feed-forward control

Solution 4: Reduce Time Step
- If oscillations numerical artifact:
- Reduce time step by 2-4×
- Check if oscillations persist

Example Fix:

Issue: NH4 oscillates between 0.2 and 3.5 mg/L daily

Diagnosis:
- Plotted NH4 and DO on same graph
- Found inverse correlation:
  • When DO high → NH4 low (good nitrification)
  • When DO low → NH4 high (nitrification fails)
- DO control cycling excessively

Fix:
1. Increased DO controller dead-band: 0.1 → 0.3 mg/L
2. Reduced gain: 1.5 → 0.8
3. Added 5-minute moving average to DO measurement

Result: NH4 stable at 0.8 ± 0.3 mg/L ✓

---

7. Denitrification Problems

7.1 "Poor Denitrification (High Effluent NO3)"

Symptoms:

• High effluent NO3 (> 5 mg/L)
• Model matches observation OR
• Model predicts better denitrification than achieved

Likely Causes:

☐ Insufficient carbon source
☐ Insufficient anoxic volume
☐ DO intrusion into anoxic zone
☐ Insufficient internal recycle
☐ Denitrification rate too low
☐ Short circuiting

Diagnostic Steps:

Step 1: Check Carbon Availability
- Calculate C:N ratio for denitrification
- Typical requirement: 3-5 kg COD / kg NO3-N

Example:
  NO3 to remove: 10 mg/L
  COD available: 20 mg/L (influent entering anoxic)
  C:N = 20/10 = 2.0 ✗ (too low, need 3-5)

Step 2: Verify Anoxic Volume
- Anoxic HRT typically 2-4 hours
- Check anoxic fraction: 15-30% of total volume

Step 3: Check DO in Anoxic Zone
- Must be < 0.5 mg/L for effective denitrification
- Preferably < 0.2 mg/L
- Check for:
  • RAS DO too high
  • Internal recycle DO too high
  • Insufficient mixing (DO pockets)

Step 4: Review Internal Recycle
- Typical: 200-400% of influent flow
- Higher IR → more NO3 to anoxic
- But also dilutes carbon source

Solutions:

Solution 1: Add External Carbon Source
- If C:N insufficient:
- Add methanol, ethanol, or acetate
- Dose to anoxic zone
- Typical: 2.5-3.0 kg methanol / kg NO3-N

Solution 2: Increase Anoxic Volume
- If HRT < 2 hours:
- Convert portion of aerobic to anoxic
- Or add anoxic tank
- Target HRT: 2-4 hours

Solution 3: Reduce DO in Anoxic Zone
- Lower RAS DO:
  • Add degassing step
  • Use anoxic RAS holding tank
- Optimize internal recycle DO:
  • Take from low-DO portion of aerobic zone
- Improve mixing (eliminate dead zones)

Solution 4: Optimize Internal Recycle
- If too low: Increase to 300-400%
- If too high: May dilute carbon, reduce to 200-300%
- Balance NO3 return vs. carbon availability

Solution 5: Adjust Denitrification Kinetics
- If facility denitrifies better than model:
- Calibrate ηg (anoxic growth factor)
- Increase from default 0.8 to 0.85-0.9

Example Fix:

Issue: Effluent NO3 = 8 mg/L, target < 5 mg/L

Diagnosis:
- Influent COD: 400 mg/L
- N nitrified: 35 mg/L
- Internal recycle: 200% (IR = 2.0)
- COD to anoxic: 400 / (1 + 2.0) = 133 mg/L
- NO3 to anoxic: 35 × 2.0 / (1 + 2.0) = 23 mg/L
- C:N = 133 / 23 = 5.8 ✓ (should be adequate)
- Anoxic volume: 0.8 MG (10% of total 8.0 MG) ✗ (too small)

Fix:
- Converted 1.2 MG aerobic to anoxic
- New anoxic volume: 2.0 MG (25% of total)
- Anoxic HRT: 2.0 MG / (10 MGD / 24) = 4.8 hours ✓

Result: Effluent NO3 = 3.2 mg/L ✓ (meets target)

---

8. Phosphorus Removal Issues

8.1 "Bio-P Not Working"

Symptoms:

• Effluent TP high (> 1 mg/L)
• No P release in anaerobic zone
• No P uptake in aerobic zone

Likely Causes:

☐ NO3 in anaerobic zone (defeats bio-P)
☐ Insufficient VFA in influent
☐ Anaerobic volume too small
☐ DO in anaerobic zone
☐ Temperature too low
☐ Wrong model (ASM1 doesn't model bio-P)

Diagnostic Steps:

Step 1: Verify Model Supports Bio-P
- Check model type:
  ✗ ASM1: No bio-P
  ✓ ASM2d: Includes bio-P
  ✓ ASM3: Includes bio-P
- If ASM1, switch to ASM2d

Step 2: Check Nitrate in Anaerobic Zone
- Anaerobic zone NO3 must be < 1 mg/L
- Sources of NO3:
  • RAS from clarifier
  • Internal recycle from aerobic
  • Insufficient pre-anoxic denitrification

Step 3: Verify VFA Availability
- VFA required for PAO selection
- Typical: 50-100 mg COD/L as VFA
- Check influent characterization:
  • VFA measured?
  • Readily biodegradable fraction adequate?

Step 4: Check Anaerobic Conditions
- True anaerobic (DO < 0.1 mg/L)
- No NO3 (< 1 mg/L)
- Temperature > 10°C
- pH = 6.5-8.0

Solutions:

Solution 1: Eliminate NO3 in Anaerobic Zone
- Add pre-anoxic zone before anaerobic
- Denitrify RAS before anaerobic
- Typical configuration:
  Influent → Pre-Anoxic → Anaerobic → Anoxic → Aerobic

Solution 2: Increase VFA/Readily Biodegradable COD
- If influent VFA low:
  • Add fermentation step (primary fermentation)
  • Dose external VFA source (acetate)
- Adjust COD fractionation (more SS, less XS)

Solution 3: Increase Anaerobic Volume
- Typical anaerobic fraction: 10-20% of total
- HRT: 1-2 hours
- If too small, PAOs don't have time for P release

Solution 4: Improve Anaerobic Conditions
- Remove any aeration
- Ensure complete mixing (no stratification)
- Check DO < 0.1 mg/L
- Insulate tank in winter (if temp low)

Solution 5: Adjust PAO Kinetic Parameters (ASM2d)
- If bio-P observed but not modeled:
- Calibrate PAO parameters:
  • qPP (P uptake rate)
  • qPHA (PHA storage rate)
  • YPO4 (poly-P content)

Example Fix:

Issue: Bio-P process designed but effluent TP = 5 mg/L (same as influent)

Diagnosis:
- Model: ASM2d ✓
- Anaerobic zone: 1.5 MG ✓
- Checked anaerobic zone results:
  • DO: 0.05 mg/L ✓
  • NO3: 8.2 mg/L ✗ (Problem!)
- RAS from clarifier bringing NO3 to anaerobic zone
- NO3 prevents P release

Fix:
- Added pre-anoxic zone (1.0 MG) before anaerobic
- Denitrifies RAS NO3 before anaerobic
- Configuration: Pre-Anox → Anaerobic → Anoxic → Aerobic

Result:
- Anaerobic NO3: 0.3 mg/L ✓
- P release observed: +8 mg P/L
- P uptake in aerobic: -9 mg P/L
- Effluent TP: 0.6 mg/L ✓ (bio-P working!)

---

9. Settling and Clarification

9.1 "High Effluent TSS"

Symptoms:

• Effluent TSS > 10 mg/L
• Model predicts poor settling
• Solids carryover

Likely Causes:

☐ Clarifier overload (hydraulic or solids)
☐ Poor settling characteristics (bulking)
☐ Short circuiting
☐ Wind/thermal currents
☐ Incorrect settling parameters

Diagnostic Steps:

Step 1: Check Clarifier Loading
- Hydraulic loading:
  Surface overflow rate (SOR) = Flow / Area
  Typical limit: 400-600 gpd/ft² (16-24 m³/m²/day)

- Solids loading:
  Solids flux = MLSS × (Q + RAS) / Area
  Typical limit: 20-40 lb/ft²/day (100-200 kg/m²/day)

Step 2: Evaluate Settling Properties
- Check SVI (Sludge Volume Index):
  Good: 50-100 mL/g
  Marginal: 100-150 mL/g
  Poor (bulking): 150-300 mL/g

- Settling velocity related to SVI:
  v0 (m/day) ≈ 10,000 / SVI

Step 3: Review Settling Model Parameters
- Takács model parameters:
  • v0: Maximum settling velocity (m/day)
  • rp: Practical minimum velocity (m/day)
  • rh: Hindered settling parameter (L/g)

Solutions:

Solution 1: Reduce Clarifier Loading
- Hydraulic:
  • Reduce peak flow (equalization)
  • Add clarifier capacity

- Solids:
  • Reduce MLSS (increase WAS)
  • Reduce RAS flow (if possible)
  • Add clarifier capacity

Solution 2: Improve Settling Characteristics
- If bulking (high SVI):
  • Identify cause (filamentous organisms)
  • Adjust F:M ratio
  • Modify SRT
  • Add selector zone
  • Dose chlorine (temporary fix)

Solution 3: Calibrate Settling Parameters
- Measure actual settling:
  • Stirred settling column test
  • Zone settling velocity
  • Hindered settling behavior

- Adjust model parameters:
  • v0 to match zone settling
  • rh to match hindered settling
  • Typical ranges:
    v0: 100-400 m/day
    rp: 0.5-1.0 m/day
    rh: 0.0003-0.0006 L/g

Solution 4: Check Clarifier Configuration
- Verify geometry correct (depth, diameter)
- Check feed point location
- Ensure proper baffling modeled

Example Fix:

Issue: Effluent TSS = 18 mg/L, target < 10 mg/L

Diagnosis:
- Clarifier area: 10,000 ft²
- Peak flow: 15 MGD
- SOR = 15,000,000 / 10,000 = 1,500 gpd/ft² ✗ (way too high!)
- Limit: 400-600 gpd/ft²
- Clarifier hydraulically overloaded at peak flow

Fix Option 1 (Operational):
- Reduce peak flow via equalization
- New peak: 12 MGD
- SOR = 1,200 gpd/ft² (still high, but better)

Fix Option 2 (Capital):
- Add third clarifier (total area → 15,000 ft²)
- SOR at 15 MGD = 1,000 gpd/ft² ✓ (acceptable)

Implemented: Option 1 (operational fix)
Result: Effluent TSS = 8 mg/L ✓

---

10. Data Import/Export Issues

10.1 "Data Import Failed"

Symptoms:

• Error when importing CSV/Excel file
• Data not appearing in model
• Partial import only

Likely Causes:

☐ Incorrect file format
☐ Missing headers
☐ Date/time format issues
☐ Special characters in data
☐ Unit mismatch

Diagnostic Steps:

Step 1: Verify File Format
- Supported: CSV, Excel (.xlsx, .xls), TXT (tab-delimited)
- Check file extension correct
- Open in Excel/Notepad to inspect

Step 2: Check Header Row
- First row must contain column names
- Names must match ErgoPlanner parameters
- Case-sensitive? Check documentation

Step 3: Inspect Data Format
- Dates: YYYY-MM-DD or MM/DD/YYYY
- Numbers: Decimal point (not comma)
- No special characters ($, %, units in data)
- No blank rows

Step 4: Review Error Message
- ErgoPlanner error log gives details
- Help → View Import Log
- Look for specific row/column mentioned

Solutions:

Solution 1: Fix File Format
Standard CSV format:
Date,Flow,BOD,TSS,TKN,TP
2024-01-01,10.5,205,225,42,6.2
2024-01-02,10.8,198,218,40,6.0
...

Common errors to fix:
✗ Commas in numbers: 10,500 → 10500 or 10.5
✗ Units in data: 10.5 MGD → 10.5
✗ Text in numeric columns: "N/A" → blank or 0

Solution 2: Standardize Date Format
- Use ISO format: YYYY-MM-DD
- Or configure ErgoPlanner date parser:
  Data → Import → Settings → Date Format

Solution 3: Map Columns
- If column names don't match:
- Data → Import → Column Mapping
- Manually map file columns to ErgoPlanner parameters

Solution 4: Clean Data in Excel
- Remove formatting (currency, percentage)
- Check for hidden characters
- Save as CSV (not "CSV UTF-8" if encoding issues)

Example Fix:

Error: "Import failed at row 45: invalid number format"

Diagnosis:
- Opened CSV file
- Row 45, BOD column: "205 mg/L" (has units)
- ErgoPlanner expects pure number

Fix:
- Excel find/replace: " mg/L" → "" (remove units)
- Verified all data columns numeric only
- Re-saved as CSV

Result: Import successful, all 365 rows loaded ✓

---

Quick Reference: Error Messages

Common Error Messages and Quick Fixes:

Error Message	Quick Fix
"Negative concentration detected"	Reduce time step, apply non-negativity constraints
"Mass balance error > 10%"	Check recycle streams, verify influent fractionation
"Model did not converge"	Increase iterations, improve initial conditions
"Integration error at time X"	Reduce time step, check input data at time X
"Insufficient aeration capacity"	Increase blower capacity or reduce load
"SRT below minimum for nitrification"	Reduce WAS flow, increase SRT
"Division by zero"	Check for zero values in flow or concentration
"File import failed"	Verify CSV format, check headers, remove units from data

---

Getting Additional Help

If This Guide Doesn't Resolve Your Issue:

1. Check Documentation

   • User Manual: Help → User Guide
   • Video Tutorials: Help → Tutorials
   • FAQ: Help → Frequently Asked Questions

2. Search Community Forum

   • forum.ergoplanner.com
   • Search for similar issues
   • Post detailed question if needed

3. Contact Support

   • support@ergoplanner.com
   • Include:
     • ErgoPlanner version
     • Error message (full text)
     • Steps to reproduce
     • Model file (if possible)
     • Screenshots

4. Professional Consulting

   • For complex calibration issues
   • Custom model development
   • Training and workshops
   • consulting@ergoplanner.com

---

Summary

This troubleshooting guide covers the most common issues in ErgoPlanner modeling:

• Simulation Errors: Configuration and setup problems
• Convergence: Iteration and solver issues
• Mass Balance: Accounting and conservation errors
• Unrealistic Results: Physical impossibilities
• Performance: Speed and efficiency
• Nitrification: NH4 removal problems
• Denitrification: NO3 removal issues
• Phosphorus: Bio-P challenges
• Settling: Clarifier performance
• Data: Import/export problems

General Troubleshooting Approach:

1. Identify symptoms clearly
2. Review likely causes
3. Perform systematic diagnostics
4. Apply targeted solutions
5. Verify fix worked
6. Document for future reference

Remember: Most issues have straightforward solutions once properly diagnosed. Work systematically, document changes, and don't hesitate to seek help when needed.

---

Last Updated: January 2025 Version: 1.0