{"id":27036730,"url":"https://github.com/molmod/psiflow","last_synced_at":"2025-12-24T18:37:40.131Z","repository":{"id":65551286,"uuid":"567671275","full_name":"molmod/psiflow","owner":"molmod","description":"Interatomic potential development library","archived":false,"fork":false,"pushed_at":"2024-04-13T16:35:45.000Z","size":7116,"stargazers_count":71,"open_issues_count":1,"forks_count":3,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-04-14T06:55:34.052Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://molmod.github.io/psiflow","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/molmod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-11-18T09:57:59.000Z","updated_at":"2024-04-15T11:18:41.210Z","dependencies_parsed_at":"2023-09-22T13:21:51.145Z","dependency_job_id":"b5518b52-2b62-4640-83d1-f7fbba75d34f","html_url":"https://github.com/molmod/psiflow","commit_stats":null,"previous_names":["molmod/psiflow"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molmod%2Fpsiflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molmod%2Fpsiflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molmod%2Fpsiflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molmod%2Fpsiflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/molmod","download_url":"https://codeload.github.com/molmod/psiflow/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271512,"owners_count":20911587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-05T01:01:41.788Z","updated_at":"2025-12-24T18:37:40.118Z","avatar_url":"https://github.com/molmod.png","language":"Python","funding_links":[],"categories":["Molecular Dynamics"],"sub_categories":[],"readme":"![psiflow](./docs/logo_light.png#gh-light-mode-only)\n![psiflow](./docs/logo_dark.png#gh-dark-mode-only)\n\n\n![License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)\n[![Docs](https://flat.badgen.net/static/docs/passing/green)](https://molmod.github.io/psiflow)\n[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fmolmod%2Fpsiflow%2Fbadge%3Fref%3Dmain\u0026style=flat-square)](https://actions-badge.atrox.dev/molmod/psiflow/goto?ref=main)\n![Python](https://flat.badgen.net/static/python/3.10%20|%203.11/blue)\n![Code style](https://flat.badgen.net/static/code%20style/black/black)\n[![DOI](https://flat.badgen.net/static/DOI/10.1038%2Fs41524-023-00969-x)](https://www.nature.com/articles/s41524-023-00969-x)\n\n\n# Scalable Molecular Simulation\n\nPsiflow is a scalable molecular simulation engine for chemistry and materials science applications.\nIt supports:\n- **quantum mechanical calculations** at various levels of theory (GGA and hybrid DFT, post-HF methods such as MP2 or RPA, and even coupled cluster; using CP2K|GPAW|ORCA)\n- **trainable interaction potentials** as well as easy-to-use universal potentials, e.g. [MACE-MP0](https://arxiv.org/abs/2401.00096)\n- a wide range of **sampling algorithms**: NVE | NVT | NPT, path-integral molecular dynamics, alchemical replica exchange, metadynamics, phonon-based sampling, thermodynamic integration; using [i-PI](https://ipi-code.org/),\n[PLUMED](https://www.plumed.org/), ... \n\nUsers may define arbitrarily complex workflows and execute them **automatically** on local, HPC, and/or cloud infrastructure.\nTo achieve this, psiflow is built using [Parsl](https://parsl-project.org/): a parallel execution library which manages job submission and workload distribution.\nAs such, psiflow can orchestrate large molecular simulation pipelines on hundreds or even thousands of nodes.\n\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/molmod/psiflow/blob/main/docs/overview.png\" width=\"500\" class=\"center\"\u003e\n\u003c/p\u003e\n\n# Setup\n\nUse the following one-liner to create a lightweight [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) Python environment with all dependencies readily available:\n```sh\ncurl -L molmod.github.io/psiflow/install.sh | bash\n```\nThe environment can be activated by sourcing the `activate.sh` file which will be created in the current working directory.\nNext, create a `config.yaml` file which defines the compute resources. For SLURM-based HPC systems, psiflow can initialize your configuration automatically via the following command:\n```sh\npython -c 'import psiflow; psiflow.setup_slurm_config()'\n```\nExample configuration files for [LUMI](https://lumi-supercomputer.eu/), [MeluXina](https://luxembourg.public.lu/en/invest/innovation/meluxina-supercomputer.html), or [VSC](https://www.vscentrum.be/) can be found [here](https://github.com/molmod/psiflow/tree/main/configs).\nNo additional software compilation is required since all of the heavy lifting (CP2K/ORCA/GPAW, PyTorch model training, i-PI dynamics) is executed within preconfigured [Apptainer](https://apptainer.org/)/[Singularity](https://sylabs.io/singularity/) containers which are production-ready for most HPCs.\n\nThat's it! Contrary to frameworks like pyiron or aiida, psiflow does not require any databases or web servers.\nThe only requirement is that you set up a Python environment and provide a `config.yaml`.\n\n[**EXAMPLES**](https://github.com/molmod/psiflow/tree/main/examples)\n\n\u003cimg src=\"https://github.com/molmod/psiflow/blob/main/docs/api_example.png\" width=\"1000\" class=\"center\"\u003e\n\n\n# FAQ\n\n**Where do I start?**\n\nTake a brief look at the [examples](https://github.com/molmod/psiflow/tree/main/examples) or the\n[documentation](https://molmod.github.io/psiflow) to get an idea for psiflow's\ncapabilities. Next, head over to the [setup \u0026 configuration](https://molmod.github.io/psiflow/configuration/) section of the docs to get started!\n\n**Is psiflow a workflow manager?**\n\nAbsolutely not! Psiflow is a Python library which allows you to perform complex molecular simulations and scale them towards large numbers of compute nodes automatically.\nIt does not have 'fixed' workflow recipes, it does not require you to set up 'databases'\nor 'server daemons'. The only thing it does is expose a concise and powerful API to\nperform arbitrarily complex calculations in a highly efficiently manner.\n\n**Is it compatible with my cluster?**\n\nMost likely yes. Check which resource scheduling system your cluster uses (probably either\nSLURM/PBSPro/SGE). If you're not sure, ask your system administrators or open an issue\n\n**Can I use VASP with it?**\n\nYou cannot automate VASP calculations with it, but in 83% of cases there is either no need\nto use VASP, or it's very easy to quickly perform the VASP part manually, outside of psiflow,\nand do everything else (data generation, ML potential training, sampling) with psiflow.\nOpen an issue if you're not sure how to do this.\n\n**I would like to have feature X**\n\nPsiflow is continuously in development; if you're missing a feature feel free to open an\nissue or pull request!\n\n**I have a bug. Where is my error message and how do I solve it?**\n\nPsiflow covers essentially all major aspects of computational molecular simulation (most\nnotably including the executation and parallelization), so there's bound to be some bug\nonce in a while. Debugging can be challenging, and we recommend to follow the following steps in\norder:\n\n1. Check the stderr/stdout of the main Python process (i.e. the `python main.py\n   config.yaml` one). See if there are any clues. If it has contents which you don't\n   understand, open an issue. If there's seemingly nothing there, go to step 2.\n2. Check Parsl's log file. This can be found in the current working directory, under\n   `psiflow_internal/parsl.log`. If it's a long file, search for any errors using `Error`\n   or `ERROR`. If you find anything suspicious but do not know how to solve it,\n   open an issue.\n3. Check the output files of individual ML training, QM singlepoints, or i-PI molecular\n   dynamics runs. These can be found under `psiflow_internal/000/task_logs/*`.\n   Again, if you find an error but do not exactly know why it happens or how to solve it,\n   feel free to open an issue. Most likely, it will be useful to other people as well\n4. Check the actual 'jobscripts' that were generated and which were submitted to the\n   cluster. Quite often, there can be a spelling mistake in e.g. the compute project you\n   are using, or you are requesting a resource on a partition that is not available.\n   These jobscripts (and their output and error) can be found under\n   `psiflow_internal/000/submit_scripts/`.\n\n**Where do these container images come from?**\n\nThey were generated using Docker based on the recipes in this repository, and were then\nconverted to `.sif` format using `apptainer`\n\n**Can I run psiflow locally for small runs or debug purposes?**\n\nOf course! If you do not provide a `config.yaml`, psiflow will just use your local\nworkstation for its execution. See e.g. [this](https://github.com/molmod/psiflow/blob/main/configs/threadpool.yaml) or [this](https://github.com/molmod/psiflow/blob/main/configs/wq.yaml) config used for testing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmolmod%2Fpsiflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmolmod%2Fpsiflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmolmod%2Fpsiflow/lists"}