Troubleshooting¶

Common issues and how to resolve them when working with DWSIM, the FluentAPI, and the MCP Server.

Solver Convergence Issues¶

Symptom: solver fails or oscillates¶

Common causes:

Inconsistent specifications (e.g., temperature and vapor fraction = 0 below the bubble point)
Bad initial guesses for recycle streams
Wrong property package for the system

Fixes:

Re-check stream specifications for physical consistency
Provide a reasonable initial guess for recycle streams (use a forward sweep first)
Increase solver tolerance temporarily to see partial results, then tighten
For columns: try a lower number of stages first, then increase
For reactors: start with low conversion or low extent of reaction

Symptom: distillation column not converging¶

Common causes:

Feed thermal condition far from saturation
Wrong reflux ratio + bottoms flow combination (infeasible spec)
Too few stages for the required separation

Fixes:

Preheat the feed to its bubble point
Try alternative spec pairs (e.g., distillate flow + bottoms flow instead of reflux + bottoms)
Add 5-10 more stages and retry
Increase reflux ratio slightly

Symptom: recycle loop diverges¶

Common causes:

Strong nonlinearity in the loop
Property package giving discontinuous behavior near phase boundary

Fixes:

Use the Recycle unit operation's Wegstein acceleration (default)
Manually specify a tear stream estimate close to the expected solution
Check if any unit in the loop has multiple solutions (reactor with multiple roots, e.g.)

Property Package Problems¶

Symptom: density or enthalpy values look wrong¶

Diagnosis:

Compare with NIST WebBook for pure components
Check that the package is appropriate (see Property Packages Guide)
Verify temperature and pressure are within the valid range

Symptom: VLE prediction misses the azeotrope¶

Common cause: Using PR or Raoult's Law for a polar mixture.

Fix: Switch to NRTL or UNIQUAC.

Symptom: results differ between two property packages¶

This is normal. Different models extrapolate differently outside their valid range. Decide which model is more reliable for your conditions:

For hydrocarbons at moderate pressure: PR is usually best
For polar/aqueous mixtures: NRTL or UNIQUAC
For pure water/steam: always Steam Tables

FluentAPI Issues¶

Symptom: ImportError or DLL not found¶

Common causes:

DWSIM not installed or not on PATH
Wrong .NET version (DWSIM uses .NET Framework 4.7.2 on Windows)
32-bit vs 64-bit Python mismatch

Fixes:

Verify python -c "import DWSIM" works
Use 64-bit Python with 64-bit DWSIM
Check that pythonnet (pip install pythonnet) is installed
Set the DWSIM bin folder in os.environ['PATH'] before importing

Symptom: Q.Kelvin or .Atm() extension methods unavailable¶

The Q quantity helpers and Pascal/Kelvin extension methods are part of the FluentAPI namespace. Ensure you import them:

from DWSIM.Automation.FluentAPI import Flowsheet, PropertyPackages, Q

For VB-style extensions on numeric literals (100.Kelvin()), Python's syntax differs - use Q.Kelvin(100) instead.

Symptom: AttributeError on a builder method¶

The FluentAPI evolves; check the current method names in the FluentAPI reference (DWSIM.FluentAPI/docs/api/index.md).

MCP Server Issues¶

Symptom: tool returns "Unknown tool" error¶

The tool name may be wrong or the server may be running an older version. Check the available tools:

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Symptom: flowsheet_id not found¶

Each flowsheet has a unique session-scoped ID. If you restart the MCP server, the IDs are lost. Save the flowsheet to disk before stopping the server.

Symptom: solver returns errors but my flowsheet looks correct¶

Read the errors array in the solve response. Each entry tells you which object failed and why.

Plus / Patreon Edition Features¶

If you see "Plus required" errors, the operation needs DWSIM Plus / Patreon Edition activation:

Reverse Osmosis
Refining unit operations (HDS, Reformer, FCC, etc.)
TEA module
LCA module
Electrolyte NRTL

To activate, follow the Patron Activation guide in the FluentAPI docs (DWSIM.FluentAPI/docs/getting-started/patron-activation.md).

Performance Issues¶

Symptom: simulations take very long¶

Common causes:

Large number of components (> 30) with rigorous property packages
Recycle loop with slow convergence
Distillation column with many stages

Fixes:

Lump similar components into pseudo-components
Use a simpler property package for screening, switch to rigorous for final design
Reduce solver tolerance for early iterations, tighten for final solve

Symptom: out of memory¶

Common causes:

Very large simulations
Memory leaks from running many simulations in a Python loop without cleanup

Fixes:

Restart the Python process between large runs
Call fs.Dispose() (or equivalent) after each simulation
Use 64-bit Python and DWSIM

Getting Help¶

DWSIM Forums: https://www.dwsim.org/forum
GitHub Issues: https://github.com/DanWBR/dwsim
Documentation: see DWSIM.FluentAPI/docs/, DWSIM.MCPServer/docs/, and the main DWSIM help in PlatformFiles/Common/docs/dwsim-help/
Validation Tests: DWSIM.Validation.Tests/ contains tested example simulations