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: ModuleNotFoundError: No module named 'DWSIM.Automation.FluentAPI'¶

DWSIM is a .NET Framework application, so pythonnet has to load that runtime before import clr, and the DWSIM folder and its unitops, ppacks and extenders subfolders have to be on sys.path (the FluentAPI assembly references DLLs that live in them; when they are missing the namespace silently comes up empty). Every example script starts with this block:

import os
import sys

import pythonnet
pythonnet.load("netfx")              # DWSIM is a .NET Framework application
import clr

DWSIM_BIN = os.environ.get("DWSIM_BIN")   # the folder that holds DWSIM.Automation.FluentAPI.dll
for sub in ("", "unitops", "ppacks", "extenders"):
    sys.path.append(os.path.join(DWSIM_BIN, sub))
clr.AddReference("DWSIM.Automation")
clr.AddReference("DWSIM.Automation.FluentAPI")

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

Checklist:

pip install pythonnet (3.x) in a 64-bit Python
Set DWSIM_BIN to the installation folder, e.g. C:\Users\<you>\AppData\Local\DWSIM
Call pythonnet.load("netfx") before the first import clr

Symptom: AttributeError: 'float' object has no attribute 'Kelvin'¶

The Q helpers are C# extension methods, and pythonnet does not attach them to Python numbers. Call them as static helpers, Q.Kelvin(300.0) and Q.Pascal(101325.0), after importing Q:

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

The same applies to the other .NET conveniences: a reaction stoichiometry is a Dictionary[String, Double] from System.Collections.Generic, and keyword arguments only work with the C# parameter names.

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