Tutorials¶

These tutorials teach you how to use QSDsan: defining components, building waste streams, assembling units into systems, and running techno-economic analysis (TEA), life cycle assessment (LCA), and uncertainty/sensitivity analyses.

All tutorials are Jupyter notebooks. Run them locally in your own Jupyter environment, or open them in your browser by clicking the badge below:

Running tutorials in Google Colab¶

You can also run any tutorial in Google Colab without installing anything locally. Colab does not include QSDsan in its default environment, so a short one-time setup is needed for each session:

Open the notebook in Colab: go to File → Open notebook → GitHub, search for QSD-Group/QSDsan, and pick the tutorial you want (under docs/source/tutorials).
Add a new cell at the very top (or use the tutorial’s first cell) and install QSDsan and EXPOsan:
```
!pip install qsdsan exposan
```
Run that cell. Colab will warn that some pre-installed packages (such as numpy and matplotlib) were already imported and that you must restart the runtime. This is expected, not an error: installing QSDsan uses different versions of those packages, but the versions already loaded into the running session cannot be swapped until you restart.
Restart the session via Runtime → Restart session.
Continue running the notebook from the cell after the install cell. Do not re-run the install cell.

Note

The restart is needed only once per session. Do not import any packages before installing, restart once after installing, and then skip the install cell, the warning will not reappear.

Note

About the YouTube walkthroughs. Some tutorials have companion videos on our YouTube channel. The videos were recorded against earlier versions of QSDsan and remain useful for the concepts and the big picture, but the notebooks here are the authoritative reference for syntax and API. Each video description lists the QSDsan version it was filmed against.

New to Python or Jupyter?¶

These tutorials assume you can read Python code, run a Jupyter notebook, and have QSDsan installed. If you are new to Python or scientific computing, work through one of the resources below first; they cover the fundamentals far better than we could here.

General Python:

The official Python tutorial, the canonical free introduction to the language.
Python for Everybody by Charles Severance, a textbook and video course aimed at absolute beginners.
Real Python, searchable tutorials on individual topics once you have the basics.

Python for researchers and engineers:

Software Carpentry: Plotting and Programming in Python, a short hands-on lesson series designed for scientists.
Scientific Python Lectures, a free course covering NumPy, SciPy, matplotlib, and pandas.

Jupyter:

Project Jupyter documentation and Try Jupyter, the official docs and an in-browser environment to experiment in.

Throughout the topical tutorials you will also find collapsible Python Aside callouts. These explain a Python concept or idiom that comes up in the surrounding code, so you can pick it up in context. Expand one if you want the explanation, or skip it if you already know the concept.

Already comfortable with Python but new to these notebooks? The Jupyter tips page covers the few Jupyter features that you might find handy when working with these tutorials.

For installing QSDsan itself, see the installation section on the main documentation page.

Topical Tutorials¶

The topical tutorials are organized in three parts.

Part I. A class-agnostic tour of QSDsan.

Quick Overview

Part II. QSDsan’s core classes. Each tutorial focuses on one or a few core classes.

Part III. Process modeling and dynamic simulation.

Reference¶

Modeling Notes & Pitfalls

Additional Resources¶

QSDsan is built on BioSTEAM, an open-source platform for process modeling and techno-economic analysis focusing on biorefineries. Some of QSDsan’s core classes and methods are inherited from BioSTEAM. You may want to refer to BioSTEAM’s documentation for the parent classes and methods.