{"id":15663870,"url":"https://github.com/jacksonburns/py2sambvca","last_synced_at":"2025-08-05T10:17:07.455Z","repository":{"id":40424080,"uuid":"289547704","full_name":"JacksonBurns/py2sambvca","owner":"JacksonBurns","description":"Simple thin client to interface python scripts with SambVca catalytic pocket fortran calculator.","archived":false,"fork":false,"pushed_at":"2024-05-07T21:16:21.000Z","size":181,"stargazers_count":22,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T18:55:00.931Z","etag":null,"topics":["chemistry","fortran","python-script"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JacksonBurns.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}},"created_at":"2020-08-22T18:49:02.000Z","updated_at":"2025-03-02T20:20:49.000Z","dependencies_parsed_at":"2024-05-06T15:39:05.728Z","dependency_job_id":null,"html_url":"https://github.com/JacksonBurns/py2sambvca","commit_stats":{"total_commits":130,"total_committers":7,"mean_commits":"18.571428571428573","dds":"0.25384615384615383","last_synced_commit":"e013dd039930bf45c120e5cbc30becc0cdbac0d9"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacksonBurns%2Fpy2sambvca","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacksonBurns%2Fpy2sambvca/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacksonBurns%2Fpy2sambvca/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacksonBurns%2Fpy2sambvca/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JacksonBurns","download_url":"https://codeload.github.com/JacksonBurns/py2sambvca/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248886317,"owners_count":21177643,"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":["chemistry","fortran","python-script"],"created_at":"2024-10-03T13:40:15.380Z","updated_at":"2025-04-14T13:08:24.517Z","avatar_url":"https://github.com/JacksonBurns.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003epy2sambvca\u003c/h1\u003e \n\u003ch3 align=\"center\"\u003eSimple thin client to interface python scripts with SambVca catalytic pocket Fortran calculator.\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"py2sambvca logo\" src=\"https://github.com/JacksonBurns/py2sambvca/blob/main/py2sambvca_logo.png\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"GitHub Repo Stars\" src=\"https://img.shields.io/github/stars/JacksonBurns/py2sambvca?style=social\"\u003e\n  \u003cimg alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/py2sambvca\"\u003e\n  \u003cimg alt=\"Total Downloads\" src=\"https://static.pepy.tech/personalized-badge/py2sambvca?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=Downloads\"\u003e\n  \u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/py2sambvca\"\u003e\n  \u003cimg alt=\"commits since\" src=\"https://img.shields.io/github/commits-since/JacksonBurns/py2sambvca/latest.svg\"\u003e\n  \u003cimg alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/py2sambvca\"\u003e\n  \u003cimg alt=\"PyPI - License\" src=\"https://img.shields.io/pypi/l/py2sambvca\"\u003e\n  \u003cimg alt=\"Test Status\" src=\"https://github.com/JacksonBurns/py2sambvca/actions/workflows/run_tests.yml/badge.svg?branch=main\u0026event=schedule\"\u003e\n\u003c/p\u003e\n\n## Installation\n`py2sambvca` is available on PyPI and can be installed like so:\n```python\npip install py2sambvca\n```\n\n`py2sambvca` has __zero__ external dependencies.\n\n### Downloading and Compiling `SambVca`\n`py2sambvca` can read and write input and output files for `SambVca` without the actual program in place, but in order to run input files you must have an executable `sambvca21.exe` (or similar) somewhere on your machine.\n\nYou can download the source code [on the `SambVca` webserver](https://www.aocdweb.com/OMtools/sambvca2.1/download/download.html) and compile it using [`gfortran`](https://gcc.gnu.org/wiki/GFortranBinaries).\n\nBy default, `py2sambvca` expects the executable to be present in the `cwd` and named `sambvca21.exe` on Windows or `sambvca21.x` on Unix-based systems. optionally, the filepath to your executable can be specified as shown below.\n\n## Usage\nAfter installation, `py2sambvca` can be added to a Python script via `import` and instantiated:\n```python\nfrom py2sambvca import p2s\n\nnhc_p2s = p2s(\n    \"test/data/nhc.xyz\",\n    [22],\n    [5],\n    [1],\n    path_to_sambvcax=\"sambvca21.exe\",\n)\n```\n\nThe required input parameters are shown below:\n - `xyz_filepath` (str): Location of .xyz molecular coordinates file for writing input data\n - `sphere_center_atom_ids` (list): ID of atoms defining the sphere center\n - `z_ax_atom_ids` (list): ID of atoms for z-axis\n - `xz_plane_atoms_ids` (list): ID of atoms for xz-plane\n\nThe following parameters are optional and will be filled with default values if not specified:\n - `atoms_to_delete_ids` (list): ID of atoms to be deleted (default None)\n - `sphere_radius` (float): Sphere radius in Angstrom (default 3.5)\n - `displacement` (float): Displacement of oriented molecule from sphere center in Angstrom (default 0.0)\n - `mesh_size` (float): Mesh size for numerical integration (default 0.10)\n - `remove_H` (int): 0/1 Do not remove/remove H atoms from Vbur calculation (default 1)\n - `orient_z` (int): 0/1 Molecule oriented along negative/positive Z-axis (default 1)\n - `write_surf_files` (int): 0/1 Do not write/write files for top and bottom surfaces (default 1)\n - `path_to_sambvcax` (str): Path to the SambVca executable. Only needed to use py2sambvca.calc()(default \"sambvca.exe\")\n - `working_dir` (path): Path to the working directory where the output and input files are generated (default os.getcwd())\n - `verbose` (int): 0 for no output, 1 for some output, 2 for the most output (default 1)\n - `radii_table` (dict or str): a dictionary of atomic symbols and their radii (angstroms), or \"default\" for the radii used in the original implementation\n\n\nFrom here, running can be done stepwise or with a single function:\n```python\nnhc_p2s.run()\n# equivalent to\nnhc_p2s.write_input()\nnhc_p2s.calc()\nnhc_p2s.parse_output()\nnhc_p2s.clean_files()\n```\n\nAll values for the total complex, quadrants, and octants are available through getters:\n\n| Total Values | Quadrant Values | Octant Values |\n| --- | --- | --- |\n| `get_free_volume()` | `get_quadrant_free_volume()` | `get_octant_free_volume()` |\n| `get_buried_volume()` | `get_quadrant_buried_volume()` | `get_octant_buried_volume()` |\n| `get_exact_volume()` | _not available_ | _not available_ |\n| `get_total_volume()` | `get_quadrant_total_volume()` | `get_octant_total_volume()` |\n| `get_percent_buried_volume()` | `get_quadrant_percent_buried_volume()` | `get_octant_percent_buried_volume()` |\n| `get_percent_free_volume()` | `get_quadrant_percent_free_volume()` | `get_octant_percent_free_volume()` |\n| `get_percent_total_volume()` | _not available_ | _not available_ |\n\nResults can also be accessed through a general getter method: `get()`, `get_quadrant_result()`, and `get_octant_result()`.\n\nAll results can also be directly accessed through dictionaries, returned from a call to `run()` or `parse_output()` and available through `p2s.total_results`, `p2s.quadrant_results`, and `p2s.octant_results`.\n\nIn case there is something else you are looking for, you can use a general purpose `get_regex()` function to return the line containing a pattern.\n\n### Examples\nHere are a couple repositories using `py2sambvca` as a Python package or extending its source code, check them out:\n - ~~[Metal-organic framework stability analysis by Hiu Ki](https://github.com/hiukiwong/mof-stability-ml)~~\n - [MOF Stability ML by Ruihan Wang](https://github.com/ruihwang/mof-stability-ml)\n\n### See Also\n - Kjell Jorner's [morfeus](https://github.com/kjelljorner/morfeus) package re-implements the original buried volume algorithm directly in Python\n\n## License\n`py2sambvca` is available under the GNU GPLv3 in accordance with the base Fortran code which is available under the same license and can be retreieved here: https://www.molnac.unisa.it/OMtools/sambvca2.1/download/download.html\n\nThe original fortran program (`sambvca21.f`) is also included in the `test` directory for testing purposes. It is still under the same terms of the GNU license:\n - This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.\n - This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n - The results obtained from using the source code shall be used for scientific purposes only, excluding industrial or commercial purposes. To use the SambVca suite for industrial or commercial purposes, contact lcavallo|@|unisa.it.\n - Proper acknowledgement shall be made to the author of the source code in publications resulting from the use of it in its original form or modified.\n - The results from using the source code are provided \"AS IS\" without warranty of any kind.\n\n## Citation\nPlease cite the `SambVca` underlying Fortran tool according to the guidelines on the buried volume webserver: [https://www.molnac.unisa.it/OMtools/sambvca2.1/help/help.html](https://www.molnac.unisa.it/OMtools/sambvca2.1/help/help.html)\n\n`py2sambvca` has been uploaded to Figshare and may be cited as: Burns, J. figshare. 2020, DOI:[10.6084/m9.figshare.12846707](https://figshare.com/articles/software/py2sambvca/12846707)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacksonburns%2Fpy2sambvca","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacksonburns%2Fpy2sambvca","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacksonburns%2Fpy2sambvca/lists"}