pyMultiwfn

A Python wrapper for automating Multiwfn 3.8 (07/01/2026) batch calculations. This project is currently in progress and is regularly maintained. Documentation for pymultiwfn can be found here.

Installation

You can now install directly from PyPI (via pip or your manager of choice, e.g., uv):

pip install pymultiwfn

Running calculations

The most simple entry-point to analysis is through the MultiwfnAnalysis class. Different Multiwfn menu entries can then by added as analyses and a MultiwfnJob will be created when the analysis is run(). There is also a possibility to create MultiwfnJob objects directly, which could be useful when executing custom menu sequences for tailored applications.

The Multiwfn object currently holds a path to the Multiwfn executable. If it is not specified, the bundled version is used.

from pymultiwfn import MultiwfnAnalysis, Menu

analysis = MultiwfnAnalysis("benzene.wfn", analyses=[
    Menu.HIRSHFELD_CHARGE,
    Menu.MAYER_BOND_ORDER,
])

analysis.run()
print(analysis.results[0].to_dict())

The MultiwfnResult dataclasses hold different types of parsed results, which can easily be serialised into JSON.

Tutorials

Tutorials can be found in the tutorials folder, reflecting the case studies. These are complete with a set of expected results to compare against.

Contributing

We actively welcome contributions from the community. If you do decide to contribute please follow the guidelines below. When using our code for other projects, please respect the Mozilla Public License 2.0. In particular:

• You must provide the original/modified files licensed under MPL, alongside a list of changes from the original files.
• If using for closed source development, you must probide original source code of the files ("file-based copyleft") under MPL alongside your software.

Development

Make sure you have uv installed on your system. Then any uv command should create a fully functional local environment:

git clone git@github.com:szczypinski-group/pyMultiwfn.git
cd pyMultiwfn
uv sync
uvx pre-commit install

Linting

Default linting settings and formatting settings (using ruff) have been created within pyproject.toml and will be applied if the optional dependencies have been installed.

Unit testing

We try to include positive and negative unit tests for each new function. Ensure the tests pass before submitting a pull request:

uv run pytest

Code standards

1. Use explicit imports wherever possible.
2. For class and function definition/calls, split arguments into multiple lines.
3. Always call functions with keyword arguments.

Conventional commits

We try to follow the conventional commits. In particular, please link to the issue that your commits are related to:

docs: update use cases in README.md

The use cases now follow the new code structure. Related to #24. Also included more detailed contribution guidelines.

Contact

If you have any question or inquiries, please create a new issue.

Referencing

If you are using this package, please reference the original Multiwfn package:

1. Tian Lu, J. Chem. Phys., 161, 082503 (2024) DOI: 10.1063/5.0216272.