QSDsan-env

A prebuilt Binder environment for QSDsan tutorials. Hosting the environment here (rather than building it on demand from the QSDsan repo) lets users click a link and reach a working Jupyter notebook in roughly 10–20 seconds instead of waiting several minutes for a fresh container build.

For users

Click the badge above. The link uses nbgitpuller (more info from this post and these instructions) to:

1. Boot a Jupyter session inside the cached QSDsan-env image.
2. Pull the latest tutorial notebooks from the main QSDsan repo.
3. Drop you in the QSDsan/docs/source/tutorials directory.

No local install required. The session is ephemeral, so save anything you want to keep before closing the tab.

For maintainers

This repo contains the Python environment for QSDsan workshops and online tutorials. CI is used to keep that environment current and reproducible.

Repo layout

File	Purpose
requirements.in	Hand-edited list of top-level packages.
requirements.txt	Fully resolved + hashed lockfile, generated by CI.
runtime.txt	Python version, synced to QSDsan's requires-python.
apt.txt	System-level apt packages (currently just graphviz).
binder/Dockerfile	Auto-written by the binder workflow; references the prebuilt image on Docker Hub so mybinder.org pulls instead of rebuilding. Do not edit by hand.

Workflows

Four GitHub Actions workflows coordinate the build and keep deps fresh:

• binder.yml: on every push to main, runs jupyterhub/repo2docker-action, pushes the resulting image to Docker Hub, and commits the cache-pointing binder/Dockerfile back to the repo. The next mybinder.org launch pulls instead of building.
• lock.yml: on changes to requirements.in (or manual dispatch), regenerates the lockfile on Linux using pip-compile with the Python version detected from QSDsan's current pyproject.toml. Also keeps runtime.txt in sync. Cross-platform locks are not portable, so this must run on Linux.
• smoke-test.yml: weekly cron and on changes to requirements.{in,txt} or root build config. Installs the lockfile (--require-hashes) on Linux and verifies the QSDsan stack imports. Catches upstream breakage before users do.
• dependabot.yml (config, not a workflow): weekly grouped PRs to bump action versions.

How to update QSDsan

1. Edit requirements.in and bump the pinned versions (qsdsan, exposan, biosteam, thermosteam). Only these four need explicit pins.
2. Push to main.
3. lock.yml runs, regenerates requirements.txt and runtime.txt on Linux, and commits the result as github-actions[bot].
4. The bot's commit does not auto-trigger downstream workflows (GitHub safety), so manually re-run binder and smoke-test from the Actions tab once the bot commit lands. Subsequent pushes for unrelated changes will trigger everything automatically.

Required repository secrets

• DOCKER_USERNAME, DOCKER_PASSWORD: a Docker Hub account that can push to $DOCKER_USERNAME/qsdsan-env.
• GITHUB_TOKEN: provided by GitHub; needs contents: write (set in repository Settings → Actions → General → Workflow permissions).