QSDsan

A package for the quantitative sustainable design of sanitation and resource recovery systems.
https://github.com/qsd-group/qsdsan

Category: Industrial Ecology
Sub Category: Life Cycle Assessment

Keywords

dynamic-simulations life-cycle-assessment process-modeling quantitative-sustainable-design resource-recovery sanitation sustainability-analysis techno-economic-analysis

Keywords from Contributors

qsdsan multi-criteria-decision-analysis biochemical-process bioprocess biorefinery centrifuge chemical-engineering distillation fermentation flash

Last synced: about 6 hours ago
JSON representation

Repository metadata

Quantitative Sustainable Design (QSD) of sanitation and resource recovery systems.

• Host: GitHub
• URL: https://github.com/qsd-group/qsdsan
• Owner: QSD-Group
• License: other
• Created: 2020-09-29T15:53:46.000Z (almost 6 years ago)
• Default Branch: main
• Last Pushed: 2026-07-23T00:12:49.000Z (6 days ago)
• Last Synced: 2026-07-23T02:09:04.984Z (6 days ago)
• Topics: dynamic-simulations, life-cycle-assessment, process-modeling, quantitative-sustainable-design, resource-recovery, sanitation, sustainability-analysis, techno-economic-analysis
• Language: Python
• Homepage: https://qsdsan.com
• Size: 74.9 MB
• Stars: 43
• Watchers: 4
• Forks: 27
• Open Issues: 1
• Releases: 5
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.rst
  • Contributing: CONTRIBUTING.rst
  • License: LICENSE.txt
  • Agents: AGENTS.md

README.rst

          ====================================================================================
QSDsan: Quantitative Sustainable Design for Sanitation and Resource Recovery Systems
====================================================================================

.. License
.. image:: https://img.shields.io/pypi/l/qsdsan?color=blue&logo=UIUC&style=flat
   :target: https://github.com/QSD-Group/QSDsan/blob/main/LICENSE.txt

.. Tested Python version
.. image:: https://img.shields.io/pypi/pyversions/qsdsan?style=flat
   :target: https://pypi.python.org/pypi/qsdsan

.. PyPI version
.. image:: https://img.shields.io/pypi/v/qsdsan?style=flat&color=blue
   :target: https://pypi.org/project/qsdsan

.. Zenodo release DOI
.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.20256569.svg
   :target: https://doi.org/10.5281/zenodo.20256569

.. Paper DOI
.. image:: https://img.shields.io/badge/qsdsan--paper-10.1039%2Fd2ew00455k-blue?style=flat
   :target: https://doi.org/10.1039/d2ew00455k

.. Website build
.. image:: https://readthedocs.org/projects/qsdsan/badge/?version=latest
   :target: https://qsdsan.com

.. GitHub test and coverage of the main branch
.. image:: https://github.com/QSD-Group/QSDsan/actions/workflows/build-coverage.yml/badge.svg?branch=main
   :target: https://github.com/QSD-Group/QSDsan/actions/workflows/build-coverage.yml

.. Codecov
.. image:: https://codecov.io/gh/QSD-Group/QSDsan/branch/main/graph/badge.svg?token=Z1CASBXEOE
   :target: https://codecov.io/gh/QSD-Group/QSDsan

.. Binder launch of tutorials https://mybinder.readthedocs.io/en/latest/howto/badges.html
.. image:: https://img.shields.io/badge/launch-binder%20%7C%20tutorial-579ACA.svg?logo=data:image/png;base64,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
   :target: https://mybinder.org/v2/gh/QSD-Group/QSDsan-env/main?urlpath=git-pull%3Frepo%3Dhttps%253A%252F%252Fgithub.com%252FQSD-group%252FQSDsan%26urlpath%3Dlab%252Ftree%252FQSDsan%252Fdocs%252Fsource%252Ftutorials%26branch%3Dmain

.. Google Group
.. image:: https://img.shields.io/badge/news-Google%20Group-4285F4?style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xNiAxMWMxLjY2IDAgMi45OS0xLjM0IDIuOTktM1MxNy42NiA1IDE2IDVjLTEuNjYgMC0zIDEuMzQtMyAzczEuMzQgMyAzIDN6bS04IDBjMS42NiAwIDIuOTktMS4zNCAyLjk5LTNTOS42NiA1IDggNUM2LjM0IDUgNSA2LjM0IDUgOHMxLjM0IDMgMyAzem0wIDJjLTIuMzMgMC03IDEuMTctNyAzLjVWMTloMTR2LTIuNWMwLTIuMzMtNC42Ny0zLjUtNy0zLjV6bTggMGMtLjI5IDAtLjYyLjAyLS45Ny4wNSAxLjE2Ljg0IDEuOTcgMS45NyAxLjk3IDMuNDVWMTloNnYtMi41YzAtMi4zMy00LjY3LTMuNS03LTMuNXoiPjwvcGF0aD48L3N2Zz4%3D
   :target: https://groups.google.com/g/qsdsan

.. YouTube video
.. image:: https://img.shields.io/endpoint?color=%23ff0000&label=YouTube%20@qsd-group&url=https%3A%2F%2Fyoutube-channel-badge-blond.vercel.app%2Fapi%2Fvideos
   :target: https://www.youtube.com/@qsd-group

|

.. contents::

|

What is ``QSDsan``?
-------------------
``QSDsan`` is an open-source, community-led platform for the quantitative sustainable design (QSD) [1]_ of sanitation and resource recovery systems [2]_. Built in Python, it integrates process modeling, system simulation, techno-economic analysis (TEA), and life cycle assessment (LCA) to support transparent, reproducible, and comprehensive evaluation of emerging technologies. Leveraging BioSTEAM [3]_, the platform provides modular and extensible tools to compare treatment configurations, evaluate resource recovery opportunities, and assess energy, cost, and sustainability tradeoffs. The platform has a range of built-in unit operations and systems, including commonly used treatment processes and biokinetic models. These capabilities support the research, development, and deployment (RD&D) of early-stage technologies for advancing sustainable water management and circular resource recovery.

All systems developed with ``QSDsan`` are included in the package `EXPOsan `_ - exposition of sanitation and resource recovery systems.


Installation
------------
``QSDsan`` is currently tested against Python 3.12, the minimum required to install it. The easiest way to install ``QSDsan`` is through ``pip`` in a command-line interface (e.g., terminal, PowerShell, etc.):

.. code::

    pip install qsdsan

To upgrade an existing installation:

.. code::

    pip install -U qsdsan

To install a specific version, replace ``X.X.X`` with the version number:

.. code::

    pip install qsdsan==X.X.X

To install the latest GitHub version from the `main branch `_:

.. code::

    pip install git+https://github.com/QSD-Group/QSDsan.git

To install from another fork and/or branch, replace ```` and ````:

.. code::

    pip install git+https://github.com//QSDsan.git@

You can also download the package from `PyPI `_.

To get the git version (use the ``depth`` flag to choose how many commit histories you want to clone):

.. code:: bash

    git clone https://github.com/QSD-Group/QSDsan.git --depth=1

Then navigate into the repository (``cd QSDsan``) and install in editable mode with development dependencies:

.. code:: bash

    pip install -e ".[dev]"


.. note::

   Using the ``depth`` flag will only clone the main branch by default. If you need other branches, add the ``--no-single-branch`` flag:

   .. code:: bash

       git clone https://github.com//QSDsan.git --depth=1 --no-single-branch


For diagram generation, ``QSDsan`` uses Graphviz. If diagrams fail to render, install Graphviz following the `official Graphviz download instructions `_ and see the `FAQ `_ for a quick check.


Homepage and Documentation
--------------------------
The ``QSDsan`` homepage and full documentation are at:

   https://qsdsan.com

It hosts the tutorials, API reference, published systems and publications, and learning materials. All tutorials are written using Jupyter Notebook; you can run your own Jupyter environment, or click the ``launch binder`` badge at the top to launch the environment in your browser.

Many tutorials have companion video walkthroughs on our `YouTube channel `_. The videos were recorded against earlier versions of ``QSDsan`` and remain useful for the concepts and the big picture, but some APIs may be outdated. Refer to the notebooks for the authoritative reference for syntax and API.


News and Updates
----------------
To receive updates, join `QSDsan's Google Group `_. Log in to your Google account and click the ``Ask to join group`` button. If you run into any problems or would like to use a non-Gmail account, please `contact us `_.


Authors and Contributing
------------------------
``QSDsan`` and its related packages are developed by the Quantitative Sustainable Design Group and the broader community. `Yalin Li `_ is the current maintainer.  See `commit history `_ for contributors who have contributed to the repository. 

If you want to contribute to ``QSDsan``, please refer to the `Contributing Guidelines `_ section of the documentation for instructions and guidelines.


License Information
-------------------
Please refer to the ``LICENSE.txt`` for information on the terms & conditions for usage of this software, and a DISCLAIMER OF ALL WARRANTIES.


References
----------
.. [1] Li, Y.; Zhang, X.; Morgan, V.L.; Lohman, H.A.C.; Rowles, L.S.; Mittal, S.; Kogler, A.; Cusick, R.D.; Tarpeh, W.A.; Guest, J.S. QSDsan: An integrated platform for quantitative sustainable design of sanitation and resource recovery systems. Environ. Sci.: Water Res. Technol. 2022, 8 (10), 2289-2303. https://doi.org/10.1039/d2ew00455k.

.. [2] Li, Y.; Trimmer, J.T.; Hand, S.; Zhang, X.; Chambers, K.G.; Lohman, H.A.C.; Shi, R.; Byrne, D.M.; Cook, S.M.; Guest, J.S. Quantitative Sustainable Design (QSD): A Methodology for the Prioritization of Research, Development, and Deployment of Technologies. (Tutorial Review) Environ. Sci.: Water Res. Technol. 2022, 8 (11), 2439–2465. https://doi.org/10.1039/D2EW00431C.

.. [3] Cortés-Peña, Y.; Kumar, D.; Singh, V.; Guest, J.S. BioSTEAM: A Fast and Flexible Platform for the Design, Simulation, and Techno-Economic Analysis of Biorefineries under Uncertainty. ACS Sustainable Chem. Eng. 2020, 8 (8), 3302–3310. https://doi.org/10.1021/acssuschemeng.9b07040.

.. create custom binder badge: https://mybinder.readthedocs.io/en/latest/howto/badges.html
        

---

Owner metadata

• Name: Quantitative Sustainable Design (QSD) Group
• Login: QSD-Group
• Email: quantitative.sustainable.design@gmail.com
• Kind: organization
• Description: Tools for quantitative sustainable design (QSD) to guide the research, development, and deployment of technologies and inform decision-making.
• Website:
• Location:
• Twitter:
• Company:
• Icon url: https://avatars.githubusercontent.com/u/68925850?v=4
• Repositories: 5
• Last ynced at: 2023-03-08T04:29:41.725Z
• Profile URL: https://github.com/QSD-Group

---

GitHub Events

Total

• Delete event: 8
• Pull request event: 16
• Fork event: 6
• Issues event: 7
• Watch event: 7
• Issue comment event: 59
• Push event: 418
• Pull request review event: 1
• Create event: 12
• Commit comment event: 7

Last Year

• Delete event: 5
• Pull request event: 8
• Fork event: 3
• Watch event: 4
• Issue comment event: 4
• Push event: 130
• Create event: 4

---

Committers metadata

Last synced: 3 days ago

Name	Email	Commits
Yalin Li	m****i@g****m	1394
Joy Zhang	j****4@g****m	526
RaiSaumitra	8****a	295
Smiti Mittal	5****l	33
Ga-Yeong Kim	g****5@g****m	32
Victoria Morgan	v****n@i****u	28
Zixuan(Zach) Wang	z****g@i****u	27
Jianan Feng	j****2@i****u	26
haclohman	6****n	16
lane-to	9****o	6
dependabot[bot]	4****]	5
Steiner	p****r@e****h	4
Yoel	y****s@g****m	2
BenGillen1998	b****8@g****m	2
lsrowles	s****c@g****m	1

Committer domains:

• illinois.edu: 3
• eawag.ch: 1

---

Issue and Pull Request metadata

Last synced: 3 days ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/qsd-group/qsdsan

---

---

---

Package metadata

• Total packages: 3
• Total downloads:
  • pypi: 1,843 last-month
• Total dependent packages: 1 (may contain duplicates)
• Total dependent repositories: 1 (may contain duplicates)
• Total versions: 96
• Total maintainers: 1

---

Dependencies

Score: 14.013016250083268