molop 0.2.2__tar.gz

molop-0.2.2/.gitignore

@@ -0,0 +1,289 @@
+# ---> Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+# *.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# MkDocs output
+public/
+.omm/
+
+# Temporary local venvs
+.tmpdocsvenv/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# ---> JupyterNotebooks
+# gitignore template for Jupyter Notebooks
+# website: http://jupyter.org/
+
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+
+# IPython
+profile_default/
+ipython_config.py
+
+# Remove previous ipynb_checkpoints
+#   git rm -r .ipynb_checkpoints/
+
+# ---> VisualStudioCode
+.vscode/*
+.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+# ---> macOS
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# OhMyOpenCode agent instructions
+AGENTS.md
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# ---> Windows
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# ---> Linux
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+test.ipynb
+molop.log
+temp.ipynb
+temp/
+docs/en/*/*.png
+docs/zh/*/*.png
+optional.json
+*.json
+!pyrightconfig.json
+ts_inital_log
+GEMINI.md
+.pyscn
+
+.sisyphus
+
+public
+.ci-docs-venv
+
+tmp/

molop-0.2.2/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2023 tmj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

molop-0.2.2/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: molop
+Version: 0.2.2
+Summary: A Python library and command-line tool for parsing and processing computational chemistry files.
+Project-URL: Homepage, https://github.com/gentle1999/MolOP
+Project-URL: Repository, https://github.com/gentle1999/MolOP
+Project-URL: Documentation, https://gentle1999.github.io/MolOP/
+Project-URL: Issues, https://github.com/gentle1999/MolOP/issues
+Project-URL: Changelog, https://gentle1999.github.io/MolOP/en/changelog/
+Author-email: Miao-jiong Tang <mj_t@zju.edu.cn>
+Maintainer-email: Miao-jiong Tang <mj_t@zju.edu.cn>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Gaussian,ORCA,cheminformatics,computational chemistry,parser,quantum chemistry,xTB,xyz2mol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: joblib>=1.5.1
+Requires-Dist: molgr>=0.1.2
+Requires-Dist: pandas>=2.3.1
+Requires-Dist: pint>=0.24.2
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: rdkit-dof>=0.1.4
+Requires-Dist: rdkit>=2023.9.6
+Requires-Dist: regex<=2025.7.33
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: tqdm>=4.67.1
+Description-Content-Type: text/markdown
+
+# MolOP (Molecule OPerator)
+
+[中文](https://github.com/gentle1999/MolOP/blob/main/README.zh.md) |
+[English](https://github.com/gentle1999/MolOP/blob/main/README.md)
+
+[![PyPI](https://img.shields.io/pypi/v/molop.svg)](https://pypi.org/project/molop/)
+[![Python](https://img.shields.io/pypi/pyversions/molop.svg)](https://pypi.org/project/molop/)
+[![Typing: Typed](https://img.shields.io/badge/typing-typed-blue.svg)](https://typing.python.org/en/latest/spec/distributing.html#packaging-type-information)
+[![Status](https://img.shields.io/pypi/status/molop.svg)](https://pypi.org/project/molop/)
+[![Wheel](https://img.shields.io/pypi/wheel/molop.svg)](https://pypi.org/project/molop/)
+[![Downloads](https://img.shields.io/pypi/dm/molop.svg)](https://pypi.org/project/molop/)
+[![CI](https://github.com/gentle1999/MolOP/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/gentle1999/MolOP/actions/workflows/ci.yaml)
+[![Docs](https://github.com/gentle1999/MolOP/actions/workflows/docs-deploy.yml/badge.svg?branch=main)](https://gentle1999.github.io/MolOP/)
+[![License](https://img.shields.io/github/license/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/blob/main/LICENSE)
+[![Last commit](https://img.shields.io/github/last-commit/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/commits/main/)
+[![Issues](https://img.shields.io/github/issues/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/issues)
+[![Stars](https://img.shields.io/github/stars/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/stargazers)
+[![Forks](https://img.shields.io/github/forks/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/network/members)
+
+MolOP is a Python 3.10+ library and command-line tool for computational chemistry files. It selects
+a registered reader from file content and maps different quantum-chemistry programs and structure
+formats into common batch, file, frame, and scientific-result containers. Downstream processing does
+not need a separate extraction path for every program.
+
+## Installation
+
+```bash
+pip install molop
+```
+
+Verify the installation:
+
+```bash
+python -c "import molop; print(molop.__version__)"
+molop --help
+```
+
+`molop --help` should list the `parse` command.
+
+<details>
+<summary>Verification output shape</summary>
+
+```text
+<version>
+Usage: molop [OPTIONS] COMMAND [ARGS]...
+...
+  parse       Parse files into a FileBatchModelDisk state, then run...
+```
+
+</details>
+
+## Read different quantum-chemistry files through one model
+
+This workflow uses the [Gaussian 16 example](https://gentle1999.github.io/MolOP/assets/examples/mn_complex_sp.log)
+and [ORCA 6 example](https://gentle1999.github.io/MolOP/assets/examples/water_mp2.out) as two
+representative inputs. Save both files in the current directory, then run:
+
+```python
+from molop import AutoParser
+
+batch = AutoParser(["mn_complex_sp.log", "water_mp2.out"], n_jobs=1)
+print(type(batch).__name__, len(batch))
+
+for parsed_file in batch:
+    frame = parsed_file[-1]
+    energy = frame.energies.total_energy.m_as("hartree")
+    print(parsed_file.detected_format_id, frame.qm_software, frame.method, energy)
+```
+
+<details>
+<summary>Output</summary>
+
+```text
+FileBatchModelDisk 2
+g16log Gaussian DFT -2182.472195
+orcaout ORCA MP2 -74.999374598107
+```
+
+</details>
+
+Both samples enter one `FileBatchModelDisk` and expose results through the same public fields. New
+readers follow the same container contract. Missing fields remain `None`; MolOP does not synthesize
+scientific results that the source did not provide.
+
+## Common tasks
+
+### Export a batch CSV
+
+```python
+from molop import AutoParser
+
+batch = AutoParser("water_mp2.out", n_jobs=1)
+summary = batch.to_summary_df(
+    frame=-1,
+    brief=False,
+    flatten_columns=True,
+)
+summary.to_csv("summary.csv", index=False)
+print(summary.shape)
+```
+
+For the bundled `water_mp2.out` example, the complete table has one row and 23 columns. Replace the
+input with a path or glob for a batch:
+
+<details>
+<summary>Output</summary>
+
+```text
+(1, 23)
+```
+
+</details>
+
+The result is `summary.csv` with one row per successfully parsed file and unit-bearing columns such
+as `Energy.total_energy.hartree`. [Notebook 02](https://gentle1999.github.io/MolOP/en/examples/02-batch-summary-filter-select/)
+renders the complete DataFrame from this call without selecting a temporary subset of columns.
+
+### Filter and export structures
+
+```bash
+molop -q parse "water_mp2.out" --n-jobs 1 \
+  filter-state --state normal \
+  format-transform --format xyz --output-dir structures
+```
+
+The command creates:
+
+<details>
+<summary>Created files</summary>
+
+```text
+structures/water_mp2.xyz
+```
+
+</details>
+
+Replace `water_mp2.out` with a path or glob for your own batch.
+
+## Supported scope
+
+- QM outputs: Gaussian log/fchk, ORCA output, and xTB output.
+- QM inputs: Gaussian and ORCA input reading and canonical writing.
+- Structure formats: XYZ, SDF/MOL, SMILES, and a CML writer.
+- Common results: structures, energies, thermochemistry, vibrations, orbitals,
+  atomic populations, dipole/polarizability, NMR, and calculation status,
+  depending on the format and printed source content.
+
+See the
+[format overview](https://gentle1999.github.io/MolOP/en/reference/format_support/)
+for exact reader/writer status and field boundaries.
+
+MolOP does not run quantum chemistry calculations and is not a dedicated
+molecular viewer or molecular dynamics engine.
+
+## Documentation
+
+- [5-minute start](https://gentle1999.github.io/MolOP/en/getting_started/quickstart/)
+- [Read calculation results](https://gentle1999.github.io/MolOP/en/guides/results/)
+- [Batch summaries](https://gentle1999.github.io/MolOP/en/guides/batch/)
+- [Filter and select](https://gentle1999.github.io/MolOP/en/guides/filtering/)
+- [Convert and export](https://gentle1999.github.io/MolOP/en/guides/conversion/)
+- [Optional structure recovery and graph visualization](https://gentle1999.github.io/MolOP/en/guides/structure-recovery/)
+- [Contributing](https://gentle1999.github.io/MolOP/en/contributing/)
+
+## Development
+
+```bash
+git clone https://github.com/gentle1999/MolOP.git
+cd MolOP
+uv sync
+make check
+```
+
+See the documentation site's Developer section for implementation contracts
+and quality gates.
+
+## Citation and license
+
+If MolOP helps your research, please cite:
+
+> MolOP (Molecule OPerator), <https://github.com/gentle1999/MolOP>
+
+This project is licensed under the
+[MIT License](https://github.com/gentle1999/MolOP/blob/main/LICENSE).

molop-0.2.2/README.md

@@ -0,0 +1,184 @@
+# MolOP (Molecule OPerator)
+
+[中文](https://github.com/gentle1999/MolOP/blob/main/README.zh.md) |
+[English](https://github.com/gentle1999/MolOP/blob/main/README.md)
+
+[![PyPI](https://img.shields.io/pypi/v/molop.svg)](https://pypi.org/project/molop/)
+[![Python](https://img.shields.io/pypi/pyversions/molop.svg)](https://pypi.org/project/molop/)
+[![Typing: Typed](https://img.shields.io/badge/typing-typed-blue.svg)](https://typing.python.org/en/latest/spec/distributing.html#packaging-type-information)
+[![Status](https://img.shields.io/pypi/status/molop.svg)](https://pypi.org/project/molop/)
+[![Wheel](https://img.shields.io/pypi/wheel/molop.svg)](https://pypi.org/project/molop/)
+[![Downloads](https://img.shields.io/pypi/dm/molop.svg)](https://pypi.org/project/molop/)
+[![CI](https://github.com/gentle1999/MolOP/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/gentle1999/MolOP/actions/workflows/ci.yaml)
+[![Docs](https://github.com/gentle1999/MolOP/actions/workflows/docs-deploy.yml/badge.svg?branch=main)](https://gentle1999.github.io/MolOP/)
+[![License](https://img.shields.io/github/license/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/blob/main/LICENSE)
+[![Last commit](https://img.shields.io/github/last-commit/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/commits/main/)
+[![Issues](https://img.shields.io/github/issues/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/issues)
+[![Stars](https://img.shields.io/github/stars/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/stargazers)
+[![Forks](https://img.shields.io/github/forks/gentle1999/MolOP.svg)](https://github.com/gentle1999/MolOP/network/members)
+
+MolOP is a Python 3.10+ library and command-line tool for computational chemistry files. It selects
+a registered reader from file content and maps different quantum-chemistry programs and structure
+formats into common batch, file, frame, and scientific-result containers. Downstream processing does
+not need a separate extraction path for every program.
+
+## Installation
+
+```bash
+pip install molop
+```
+
+Verify the installation:
+
+```bash
+python -c "import molop; print(molop.__version__)"
+molop --help
+```
+
+`molop --help` should list the `parse` command.
+
+<details>
+<summary>Verification output shape</summary>
+
+```text
+<version>
+Usage: molop [OPTIONS] COMMAND [ARGS]...
+...
+  parse       Parse files into a FileBatchModelDisk state, then run...
+```
+
+</details>
+
+## Read different quantum-chemistry files through one model
+
+This workflow uses the [Gaussian 16 example](https://gentle1999.github.io/MolOP/assets/examples/mn_complex_sp.log)
+and [ORCA 6 example](https://gentle1999.github.io/MolOP/assets/examples/water_mp2.out) as two
+representative inputs. Save both files in the current directory, then run:
+
+```python
+from molop import AutoParser
+
+batch = AutoParser(["mn_complex_sp.log", "water_mp2.out"], n_jobs=1)
+print(type(batch).__name__, len(batch))
+
+for parsed_file in batch:
+    frame = parsed_file[-1]
+    energy = frame.energies.total_energy.m_as("hartree")
+    print(parsed_file.detected_format_id, frame.qm_software, frame.method, energy)
+```
+
+<details>
+<summary>Output</summary>
+
+```text
+FileBatchModelDisk 2
+g16log Gaussian DFT -2182.472195
+orcaout ORCA MP2 -74.999374598107
+```
+
+</details>
+
+Both samples enter one `FileBatchModelDisk` and expose results through the same public fields. New
+readers follow the same container contract. Missing fields remain `None`; MolOP does not synthesize
+scientific results that the source did not provide.
+
+## Common tasks
+
+### Export a batch CSV
+
+```python
+from molop import AutoParser
+
+batch = AutoParser("water_mp2.out", n_jobs=1)
+summary = batch.to_summary_df(
+    frame=-1,
+    brief=False,
+    flatten_columns=True,
+)
+summary.to_csv("summary.csv", index=False)
+print(summary.shape)
+```
+
+For the bundled `water_mp2.out` example, the complete table has one row and 23 columns. Replace the
+input with a path or glob for a batch:
+
+<details>
+<summary>Output</summary>
+
+```text
+(1, 23)
+```
+
+</details>
+
+The result is `summary.csv` with one row per successfully parsed file and unit-bearing columns such
+as `Energy.total_energy.hartree`. [Notebook 02](https://gentle1999.github.io/MolOP/en/examples/02-batch-summary-filter-select/)
+renders the complete DataFrame from this call without selecting a temporary subset of columns.
+
+### Filter and export structures
+
+```bash
+molop -q parse "water_mp2.out" --n-jobs 1 \
+  filter-state --state normal \
+  format-transform --format xyz --output-dir structures
+```
+
+The command creates:
+
+<details>
+<summary>Created files</summary>
+
+```text
+structures/water_mp2.xyz
+```
+
+</details>
+
+Replace `water_mp2.out` with a path or glob for your own batch.
+
+## Supported scope
+
+- QM outputs: Gaussian log/fchk, ORCA output, and xTB output.
+- QM inputs: Gaussian and ORCA input reading and canonical writing.
+- Structure formats: XYZ, SDF/MOL, SMILES, and a CML writer.
+- Common results: structures, energies, thermochemistry, vibrations, orbitals,
+  atomic populations, dipole/polarizability, NMR, and calculation status,
+  depending on the format and printed source content.
+
+See the
+[format overview](https://gentle1999.github.io/MolOP/en/reference/format_support/)
+for exact reader/writer status and field boundaries.
+
+MolOP does not run quantum chemistry calculations and is not a dedicated
+molecular viewer or molecular dynamics engine.
+
+## Documentation
+
+- [5-minute start](https://gentle1999.github.io/MolOP/en/getting_started/quickstart/)
+- [Read calculation results](https://gentle1999.github.io/MolOP/en/guides/results/)
+- [Batch summaries](https://gentle1999.github.io/MolOP/en/guides/batch/)
+- [Filter and select](https://gentle1999.github.io/MolOP/en/guides/filtering/)
+- [Convert and export](https://gentle1999.github.io/MolOP/en/guides/conversion/)
+- [Optional structure recovery and graph visualization](https://gentle1999.github.io/MolOP/en/guides/structure-recovery/)
+- [Contributing](https://gentle1999.github.io/MolOP/en/contributing/)
+
+## Development
+
+```bash
+git clone https://github.com/gentle1999/MolOP.git
+cd MolOP
+uv sync
+make check
+```
+
+See the documentation site's Developer section for implementation contracts
+and quality gates.
+
+## Citation and license
+
+If MolOP helps your research, please cite:
+
+> MolOP (Molecule OPerator), <https://github.com/gentle1999/MolOP>
+
+This project is licensed under the
+[MIT License](https://github.com/gentle1999/MolOP/blob/main/LICENSE).