Common Errors

Note

For modeling-time surprises (a number that looks wrong, a unit that sized weirdly, a sim that won’t converge), see Modeling Notes & Pitfalls.

Graphviz Installation

Install Graphviz if you want to use QSDsan’s diagram methods.

Graphviz installation has two parts:

  1. The Graphviz software, which provides the dot executable used to render diagrams.

  2. The Python graphviz package, which lets Python call Graphviz.

For the Graphviz software, follow the official Graphviz download instructions for your operating system. If you use conda, the conda-forge package can install both the software and Python interface:

conda install -c conda-forge python-graphviz

If you do not use conda, install the Graphviz software first, then install the Python interface in your active Python environment:

pip install graphviz

To check that Graphviz is installed correctly, run:

dot -V

If dot is not found, restart your terminal/editor and try again. If it still fails, follow the Graphviz instructions for adding the Graphviz bin directory to your system PATH.

When using diagram(), if you run into a graphviz error similar to:

FileNotFoundError: [Errno 2] No such file or directory: 'dot'

or

ExecutableNotFound: failed to execute ['dot', '-Kdot', '-Tpng'], make sure the Graphviz executables are on your systems' PATH

or if you cannot get any diagram at all. It is likely that your graphviz is not configured correctly.

Note

For the case where you don’t have any diagram, the biosteam.preferences.raise_exception is set to False, you can see the error by changing that to True.

In most cases, this means either the Graphviz software is not installed or the dot executable is not available on your system PATH.

ModuleNotFoundError

Sometimes (even though you have downloaded/cloned/installed qsdsan), you still cannot see:

ModuleNotFoundError: No module named 'qsdsan'

There are multiple possible reasons:

  • If you have multiple conda environments, make sure you first do conda activate <ENV NAME> (replace <ENV NAME> with the actual name of your environment) to activate the environment.

  • If you are using a cloned version of QSDsan for development, install it from the cloned repository with pip install -e ".[dev]".

  • If you are using Jupyter Notebook

    • Make sure Jupyter is using the same environment where QSDsan is installed.

    • To add your active environment as a Jupyter kernel, run this in your command-line interface (CLI, e.g., Anaconda Prompt, terminal; first do conda activate <ENV NAME> if you are using a virtual environment, and replace <KERNEL NAME> with the name you like):

      python -m ipykernel install --user --name <KERNEL_NAME>

      Note

      If you do not have ipykernel, firstly do conda install ipykernel

      Then when you open the Jupyter Notebook, select the <KERNEL NAME> kernel when you create a new notebook you can find more details in this post about enabling multiple kernels in Jupyter Notebook.

underlying object has vanished

This error is related to numba caching, we haven’t figured out the exact mechanism, but clearing cache will help resolve it. One/both of the following approaches should work:

  1. Clear cache. Remove all .pyc, .nbc, and .nbi files from the relevant package or project directory:

    get-childitem . -recurse -include *.pyc, *.nbc, *.nbi | remove-item

  2. Uninstalling and reinstalling a different version of numba. Suppose you now have 0.58.1 and the newest version is 0.60.0, you can do:

    pip uninstall numba
pip install --no-cache-dir numba==0.60.0

The --no-cache-dir option is to do a fresh installation rather than using previously downloaded packages. Note that you need to exit out your editor/any other programs that are currently using numba. Otherwise the uninstallation is incomplete, you might be prompted to do a manual removal, or this won’t work.

UnicodeDecodeError

When using non-English operating systems, you may run into errors similar to (cp949 is the case of Korean Windows):

UnicodeDecodeError: 'cp949' codec can't decode byte Oxe2 in position 3426: multibyte sequence

To fix this, Windows users can look at this thread on updating the character encoding in the Windows console to UTF-8. We are not sure if this error will appear for Mac users, but let us know if you run into this and we will be happy to help with troubleshooting.

Version compatibility

QSDsan requires Python 3.12 or newer and pins specific minimum versions of biosteam, thermosteam, and other dependencies. The authoritative version table lives in pyproject.toml; the table here is a quick reference and may lag.

If you see import errors after upgrading one of those dependencies independently of QSDsan, the most reliable fix is to reinstall QSDsan in a fresh environment so the resolver picks compatible versions of everything at once.