{"id":51611404,"url":"https://github.com/braboj/corrosim","last_synced_at":"2026-07-12T08:03:57.177Z","repository":{"id":368201415,"uuid":"1283593700","full_name":"braboj/corrosim","owner":"braboj","description":null,"archived":false,"fork":false,"pushed_at":"2026-07-07T07:29:57.000Z","size":14060,"stargazers_count":1,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-07T08:12:21.137Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","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/braboj.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,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-29T04:14:16.000Z","updated_at":"2026-07-07T07:30:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/braboj/corrosim","commit_stats":null,"previous_names":["braboj/corrosim"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/braboj/corrosim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braboj%2Fcorrosim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braboj%2Fcorrosim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braboj%2Fcorrosim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braboj%2Fcorrosim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/braboj","download_url":"https://codeload.github.com/braboj/corrosim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braboj%2Fcorrosim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35385774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2026-07-12T08:03:56.434Z","updated_at":"2026-07-12T08:03:57.169Z","avatar_url":"https://github.com/braboj.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# corrosim\n\n*Density-functional-theory reactivity, adsorption dynamics, and a shareable\nreport for green corrosion inhibitors. Free software, end to end.*\n\ncorrosim screens corrosion inhibitors end to end: from a molecule and a\nmetal, it computes reactivity descriptors, estimates adsorption, ranks\ncandidates, and writes a self-contained report, all on free, open-source\nsoftware. It is built for green, plant-derived inhibitors: the **Arghel\n(*Solenostemma argel*) flavonoids** on mild steel in 1 M HCl. It also accepts\nany molecule and supported substrate.\n\n![CI](https://github.com/braboj/corrosim/actions/workflows/ci.yml/badge.svg)\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)\n\n## Features\n\n- Screen any molecule (by name or SMILES) against a metal surface\n- Rank your candidates best-first with a transparent score\n- Compute quantum reactivity descriptors (HOMO–LUMO gap, hardness, ΔN) with\n  xTB or DFT\n- Map where a molecule is reactive: Fukui indices and ESP isosurfaces\n- Estimate how it adsorbs: Monte Carlo pose search plus Brownian-dynamics RDF\n- Write one self-contained HTML report, every figure embedded\n- Run end to end on free, open-source engines (xTB, PySCF)\n\n## Quick start\n\nPrerequisites: Python 3.10+ with `pip`. No quantum engines needed for this path:\nit rebuilds the report from the committed result data.\n\n```bash\ngit clone https://github.com/braboj/corrosim\ncd corrosim\n\n# core + figure rendering + Word output\npip install -e \".[viz,report]\"\n\n# rebuild cases/arghel/report/ from cases/arghel/results/\npython -m corrosim.runs.make_report    \n```\n\nExpected output:\n\n```text\nreport written to cases/arghel/report/report.html (4248 kB, self-contained)\nword report written to cases/arghel/report/report.docx (3101 kB)\ntables in cases/arghel/report/tables/ (per-stage subfolders)\n```\n\n## Usage\n\n**Command line.** Screen the case-study set, rank it, and write a report + CSV:\n\n```bash\ncorrosim --inhibitors kaempferol,quercetin,isorhamnetin \\\n         --engine pyscf --out report.html --csv screen.csv\n```\n\nOutput (the ranking prints best-first, then the report path):\n\n```text\nRanking (best first):\n        name   gap_ev  hardness_ev  softness_inv_ev  delta_n  score\n   quercetin 4.082368     2.041184         0.489912 0.178078  0.995\nisorhamnetin 4.098977     2.049489         0.487927 0.209973  0.373\n  kaempferol 4.145686     2.072843         0.482429 0.168912 -1.368\n\nHTML report: report.html\n```\n\nUse `--engine xtb` for a sub-second ranking pass, `--input molecules.csv` to\nscreen a batch (columns `name[,smiles]`), and `--adsorption` to add a fast UFF\nvan-der-Waals physisorption estimate as an `e_ads_kjmol` column.\n\n**Python.** The same screen from a script:\n\n```python\nimport corrosim\n\ndf, html = corrosim.screen(\n    [\"kaempferol\", \"quercetin\", \"isorhamnetin\"],\n    metal=\"Fe(110)\", engine=\"xtb\", out_html=\"report.html\",\n)\nprint(corrosim.rank_inhibitors(df).iloc[0][\"name\"])\n```\n\nOutput:\n\n```text\nquercetin\n```\n\n## How it fits together\n\n| | `corrosim` (screen) | `runs/*` → `make_report` (report) |\n| --- | --- | --- |\n| Per molecule | MMFF geometry, single-point descriptors | DFT (optionally relaxed), Fukui, ESP, MC, MD, pKa |\n| Produces | one-page HTML + ranking | `cases/\u003ccase\u003e/report/` bundle with figures |\n| Speed | seconds | minutes to hours |\n\n`corrosim --plan` lists the steps a screen will run without computing them. On\nWindows the engines (`xtb`, `pyscf`) run in the `corrosim-qm` container; the venv\ndoes everything else. Full pipeline commands: [`docs/PLAYBOOK.md`](docs/PLAYBOOK.md).\n\n## Project structure\n\n| Path | Contents |\n| --- | --- |\n| `src/corrosim/` | Core package facade: `__init__`, `cli`, `molecules`, `medium`, `presets`, `fetch`; subsystem sub-packages below (ADR 0011). |\n| `src/corrosim/qm/` | `engines`, `descriptors`, `fukui`, `pka`, `speciation`, `protonation`, `cubes`; `_backend_pyscf`/`_tblite` hold the deferred pyscf/tblite imports (ADR 0015). |\n| `src/corrosim/adsorption/` | `surface`, `adsorption`, `mc`, `md`. |\n| `src/corrosim/report/` | `report`, `ranking` (canonical basis + robustness gate), `report_docx`, `report_content`, `report_layout`, `figures` (renders cubes; `qm.cubes` writes them). |\n| `src/corrosim/data/` | `inhibitors.json`: the shipped inhibitor library (name → SMILES + provenance), loaded by `molecules`; grown by the fetch tool. |\n| `src/corrosim/runs/` | Stage drivers: `run_dft`, `run_fukui`, `run_mc`, `run_md`, `run_pka`, `make_cubes`, `make_figures`, `make_report`, `compare_geometry` (+ `_cli`: shared CLI plumbing). |\n| `cases/\u003ccase\u003e/` | One co-located subtree per case study (the shipped one is `cases/arghel/`), split into `results/` and `report/`. |\n| `cases/\u003ccase\u003e/results/` | Tracked pipeline data: descriptors, Fukui, MC/MD, pKa. |\n| `cases/\u003ccase\u003e/report/` | Report bundle (`make_report`): `report.html` + `report.docx` + `figures/\u003cstage\u003e/` + `tables/\u003cstage\u003e/`. |\n| `examples/` | Sample batch CSV. |\n| `tests/` | pytest suite (QM-light, no DFT, fast). |\n| `docs/` | `pipeline.md`, `validation.md`, `ONBOARDING.md`, `PLAYBOOK.md`, `dev-journal.md`, `decisions/` (ADRs), `diagrams/` (.drawio sources). |\n| `Dockerfile`, `docker-compose.yml` | The `corrosim-qm` QM environment (PySCF + tblite). |\n\n## Development setup\n\nClone with the quality-template submodule, create a virtual environment, and\ninstall with the dev extras:\n\n```bash\ngit clone --recurse-submodules https://github.com/braboj/corrosim\ncd corrosim\n\npython -m venv .venv\n# Windows:  .venv\\Scripts\\activate    |  POSIX:  source .venv/bin/activate\npip install -e \".[dev]\"       # runtime + tests + figure rendering\n\npytest -q                     # test suite (QM-light; no Docker)\nruff check .                  # lint\nmypy                          # type-check (non-strict; CI gate)\ncomplexipy                    # cognitive-complexity ratchet (CI gate)\n```\n\n**External tool: Docker (for the quantum stages).** The DFT/xTB engines\n(`pyscf`, `tblite`, `geometric`) have no native-Windows wheels and run only in\nthe bundled `corrosim-qm` image; everything else runs in the venv.\n\n```bash\ndocker compose build qm                           # build once\ndocker compose run --rm qm pytest -q              # smoke test in the container\ndocker compose run --rm qm \\\n    python -m corrosim.runs.run_dft --out-csv cases/arghel/results/dft_descriptors_ff.csv\n```\n\nThe repo is bind-mounted at `/work`, so outputs land back in `cases/\u003ccase\u003e/results/` /\n`cases/\u003ccase\u003e/report/` and code edits need no rebuild. Long jobs (geometry-opt, MEP cubes)\nshould run detached (`docker compose run -d --name \u003cjob\u003e qm …`) so they survive\na shell exit. On Linux/macOS you may instead install the engines natively with\nthe `qm` extra (`pip install -e \".[qm]\"`).\n\n## Configuration reference\n\ncorrosim reads no secrets and needs no `.env`. The only environment variables\nare the paths to the optional external ORCA/Gaussian binaries:\n\n| Variable | Type | Default | Description |\n| --- | --- | --- | --- |\n| `ORCA_CMD` | path | `orca` | ORCA executable used by `--engine orca`. |\n| `GAUSSIAN_CMD` | path | `g16` | Gaussian executable used by `--engine gaussian`. |\n\nThe screening run is configured through CLI options (`corrosim --help`):\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `--input` / `--inhibitors` | path / list | *(one required)* | Molecules: a CSV (`name[,smiles]`) or a comma-separated list of names/SMILES. |\n| `--metal` | str | `Fe(110)` | Substrate: `Fe(110)`, `Cu(111)`, or `Al(111)`. |\n| `--medium` | str | `1 M HCl` | Medium label for the report header. |\n| `--engine` | choice | `xtb` | Quantum engine: `xtb`, `pyscf`, `orca`, `gaussian`. |\n| `--basis` | str | `6-311++G(d,p)` | PySCF basis set (ADR 0002 production level). |\n| `--xc` | str | `b3lyp` | PySCF exchange–correlation functional. |\n| `--solvent` | str | `water` | Implicit solvent (`none` for gas phase). |\n| `--adsorption` | flag | off | Add a fast UFF van-der-Waals physisorption estimate (`e_ads_kjmol`), scanned over heights at a flat orientation. |\n| `--out` | path | `corrosion_report.html` | HTML report output path. |\n| `--csv` | path | *(none)* | Also write the ranked results table to this CSV. |\n\n## Limitations\n\n- The adsorption stages (Monte Carlo pose search + Brownian MD) use a **UFF\n  van-der-Waals model** (rigid bodies, no charge transfer): bounded and good for\n  ranking and the physisorption distance, but **not a quantitative chemisorption\n  E_ads**.\n- Simulations **screen and explain**; they do not prove efficiency. Validate with\n  electrochemistry (EIS, polarization, weight loss).\n\n## Links\n\n- [Pipeline: scientific basis](docs/pipeline.md)\n- [Validation: computational and experimental](docs/validation.md)\n- [Architecture decisions (ADRs)](docs/decisions/)\n- [Onboarding guide](docs/ONBOARDING.md): setup for new contributors\n- [Operational playbook](docs/PLAYBOOK.md): day-to-day tasks and workflows\n- [Development journal](docs/dev-journal.md): session history\n- [Issue tracker](https://github.com/braboj/corrosim/issues)\n\n## License\n\nMIT. See [LICENSE](LICENSE). © 2026 Branimir Georgiev.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraboj%2Fcorrosim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbraboj%2Fcorrosim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraboj%2Fcorrosim/lists"}