# chemsmart writes the inputs, submits them to any of three schedulers, and reads the results

> A Python toolkit for quantum chemistry automation whose central promise is that the submission command does not change whether your cluster runs SLURM, Torque or a smaller in-house scheduler. The build system is more revealing than the feature list: it detects four Windows shells, and it wraps commands in a conda invocation because a swallowed exit code once let a failing test suite report as passing.

**xinglong-zhang/chemsmart** — CHEMSMART: Chemistry Simulation and Modeling Automation Toolkit

- Repository: https://github.com/xinglong-zhang/chemsmart
- Website: https://chemsmart.readthedocs.io/en/latest/
- Stars: 49 · Forks: 18
- Language: Python
- License: GPL-3.0
- Published: 2026-08-23 · Updated: 2026-08-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/xinglong-zhang-chemsmart

## One submission command across three different schedulers

The product's headline is not any individual calculation type, it is portability across clusters. The stated design is that the submission command is the same regardless of which queueing system the cluster uses, naming three of them: the two big Linux schedulers and a smaller in-house one. That claim is what the tool is for, because the usual failure mode in computational chemistry is that a workflow written on one cluster is a pile of shell substitutions that break on the next. Alongside that, the toolkit covers the three stages that would otherwise be hand written: generating the input file for the electronic structure program, generating the submission script, and analysing what comes back. The explicit promise is that users customise their own server and project settings rather than editing the package, so the code stays the same when the cluster changes.

## Windows support means four documented install routes and a preferred one

Windows is treated as a real target rather than an afterthought, and the installation documentation offers four separate routes for it: a Linux subsystem environment, a Git Bash environment, an Anaconda prompt, and the cluster route. The recommended one is stated, and it is the subsystem rather than any native Windows option, with the reason given as full functionality support. That is a candid admission that the native routes exist but are narrower. The build system backs the claim up. Its first act is to detect the operating system before invoking anything that might not exist on it, with an explicit comment that the Windows command processor cannot redirect output to the null device, which is why the detection cannot rely on the usual Unix trick. It then treats three separate Windows shell environments as Windows and picks the command processor for the platform accordingly.

## The conda wrapper exists because an exit code was being swallowed

There is a comment in the build file that explains more about the project's engineering than any feature list would. Commands are wrapped in an invocation that runs them inside the named environment, but the wrapper is skipped entirely when that environment is already active, and the comment says why: some versions of the environment manager fail to propagate the wrapped command's exit status, which allowed a failing test suite to report as a passing CI step. That is a specific bug class, caught in production, and fixed by detecting the already-active case rather than by trusting the wrapper. It also tells you the project runs its tests inside a conda environment rather than a plain virtual environment, and that continuous integration sets the environment up through a standard action that activates it directly. The help target is likewise self-documenting, deriving its own menu from inline comments rather than maintaining a separate list.

## Nearly every dependency is pinned exactly and the numeric stack is held back

The dependency list looks like a lock file that leaked into the manifest, and one entry has an explanatory comment. The structural chemistry library, the machine learning dependency, the graph library, the data frame library, the numerical library, the statistics library, the imaging library and the command line library are all pinned to exact versions with no range at all. Two things are worth pulling out of that. First, the numerical library is held at a compatible release on the one major line below current, and the comment says the cheminformatics and visualisation packages require it. Second, the visualisation package named in that comment is not itself a declared dependency, which suggests the constraint is there for a setup outside the declared set. If you are assembling an environment alongside this one, that constraint is the first constraint you will hit.

## The test framework sits in the runtime dependency list

There is a testing extra, and it is not where all the testing dependencies live. A test framework, a mocking plugin, the mocking library itself and a stub-typing package all appear among the runtime dependencies, so anyone who installs the package gets them whether or not they ever run a test. That is a mild bloat rather than a correctness problem, and it is easy to see how it happened: the package was probably developed with those installed and the extras were added later without removing them. The extras themselves are otherwise sensibly organised into three groups, a test group with coverage tooling, a development group with four formatters and linters plus a changelog generator and a requirements-file generator, and a documentation group with the documentation toolchain and a documentation linter. The presence of a separate documentation lint configuration file at the repository root suggests that group is actually enforced.

## Two licence files and a classifier that says something different

The repository root carries two licence files, one of them a lesser-licence file, which is the conventional layout for code that is dual licensed. What does not line up is the package metadata: the licence field points at a single file rather than describing the pair, and the classifier declared alongside it names a permissive licence rather than the copyleft one recorded for the repository itself. If you are distributing this, or vendoring it into something with a licence policy, that mismatch is the thing to resolve, because classifiers are what automated licence scanners read. The other metadata is tighter than the classifier: the build backend is pinned to an exact release rather than a range, the interpreter constraint uses the compatible release operator rather than a floor, which is a stricter choice than most packages make.

## Configuration is three files, and only one of them is about the cluster

The configuration documentation is split into three guides plus an overview, and the split is the design. User settings are yours: defaults you want everywhere. Server settings describe a machine: where the scheduler is, what the paths are, how jobs get submitted. Project settings are a specific body of work with its own requirements. The point of three files rather than one is visible in the introduction, which promises that a user can run different jobs on different servers by changing settings rather than code. In practice that means a project configuration should be portable between clusters if the server settings are swapped, and a user's defaults survive a change of machine. The documentation also offers a video for each of installation and configuration, hosted on two different video platforms, which is a reasonable concession that this is a tool with a learning curve.

## Three electronic structure programs, and the teaching material is video

The documentation is organised by program, and three are covered with dedicated sections. The first covers the largest program, with guides for geometry optimisation, transition state searches, conformational sampling and dynamics, a quick reaction coordinate job type, electronic structure properties, a hybrid quantum and molecular mechanics partitioning workflow, and a catch-all page for everything else. The second covers a second program with a similar set plus a single-point route and a direct-input route for people who already know what they want. The third is a lighter semi-empirical package with optimisation, single point, and Hessian and frequency guides. Molecular input formats and a conversion command have their own pages, and there is a dedicated page for preparing structures from a chemical drawing program, including an organometallic case, which tells you the authors hit real friction there.

## Conclusion

Adopt this if you run quantum chemistry on a cluster and want one workflow across sites rather than a hand written script per scheduler. The three layer configuration is the part to understand first, since server settings are where the scheduler and paths live and user settings are where your defaults go. Two things to check before you rely on it. The notice at the top of the documentation says a plain update fixes most reported problems, which means the release cadence is fast and behaviour can move under you, so pin a version. And note that the pinned chemistry stack includes a numeric library held at an older major line, so plan for that constraint rather than assuming you can upgrade it independently.

## FAQ

### Where can I buy chemical products?

This repository is not a supplier and answers no such question. It is a computational toolkit: it writes input and submission files for quantum chemistry programs, submits them to a cluster, and analyses the results. Nothing in it touches physical reagents or purchasing.

### Which quantum chemistry programs does chemsmart drive?

Three, each with its own documentation section: one large program covered for optimisation, transition states, conformational sampling, quick reaction coordinates, electronic structure properties and a partitioned molecular mechanics workflow; a second covered for optimisation, single points, transition states, reaction paths, direct input and multiscale mechanics; and a lighter semi-empirical package covered for optimisation, single points and Hessian calculations.

### How do I install chemsmart on Windows?

Four routes are documented, and the documentation recommends the Linux subsystem environment for full functionality rather than any native Windows option. The alternatives are a Git Bash environment, an Anaconda prompt, and a separate route for installing on a cluster. The build system itself detects four Windows shell environments and switches command syntax accordingly.

### How does chemsmart handle different HPC schedulers?

The submission command is the same regardless of whether the cluster runs SLURM, Torque or the smaller in-house scheduler named in the documentation. The differences between clusters live in configuration rather than code, split across user settings, server settings and project settings, and the project states that you can change those without modifying the package.

## Sources

- [Official documentation](https://chemsmart.readthedocs.io/en/latest/)
- [Official README](https://github.com/xinglong-zhang/chemsmart#readme)
- [Project repository](https://github.com/xinglong-zhang/chemsmart)
- [Release notes](https://github.com/xinglong-zhang/chemsmart/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xinglong-zhang-chemsmart