allomorph 0.1.0__tar.gz

allomorph-0.1.0/.gitignore

@@ -0,0 +1,72 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Generated artefacts
+*.lmp
+*.xyz
+*.log
+*.csv
+*.pickle
+*.pkl
+*.zip
+*.exe
+*.ipynb_checkpoints
+MNP/
+BNP/
+TNP/
+docs/_build/
+docs/_static/
+docs/_templates/
+
+# Legacy directories
+InitStruct/*NP/
+InitStruct/*log*
+MDsim/*.log
+FeatExtEng/__pycache__/
+FeatExtEng/*.log
+FeatExtEng/NCPac/*.mod
+
+# AI Assistants
+.agents/
+.antigravitycli/
+.codex
+.continue/
+.qodo/

allomorph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Yik Chang Ting
+
+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.

allomorph-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: allomorph
+Version: 0.1.0
+Summary: Toolkit for generating monometallic to trimetallic nanoparticle structural datasets for machine learning.
+Project-URL: Homepage, https://github.com/jonathan-ting/allomorph
+Project-URL: Bug Tracker, https://github.com/jonathan-ting/allomorph/issues
+Author: Jonathan Yik Chang Ting
+License: MIT License
+        
+        Copyright (c) 2026 Jonathan Yik Chang Ting
+        
+        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.
+License-File: LICENSE
+Keywords: EAM,LAMMPS,machine-learning,materials-science,molecular-dynamics,nanoparticles
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Requires-Dist: ase
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Provides-Extra: dev
+Requires-Dist: jupyterlab; extra == 'dev'
+Requires-Dist: myst-nb; extra == 'dev'
+Requires-Dist: myst-parser; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: python-semantic-release; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: sphinx; extra == 'dev'
+Requires-Dist: sphinx-autoapi; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AlloMorph
+
+---
+
+## Description
+
+AlloMorph is a Python toolkit for generating initial structural models of monometallic, bimetallic, and trimetallic nanoparticles. It is designed to create large-scale datasets for atomistic simulations and machine learning applications.
+
+![](https://raw.githubusercontent.com/Jon-Ting/allmorph/main/docs/figs/TNPs_generation_flowchart.png)
+
+---
+
+## Installation
+
+This package uses [uv](https://docs.astral.sh/uv/) for dependency management and packaging. For detailed information on external tool requirements (LAMMPS, NCPac, etc.), see [DEPENDENCIES.md](DEPENDENCIES.md).
+
+```bash
+# Clone the repository
+git clone https://github.com/jonathan-ting/allomorph.git
+cd allomorph
+
+# Create a virtual environment and install dependencies
+uv venv
+uv pip install -e ".[dev]"
+```
+
+Alternatively, you can install directly with pip:
+
+```bash
+pip install allomorph
+```
+
+---
+
+## Usage
+
+The core `allomorph` command provides a streamlined interface for structure generation:
+
+```bash
+# Generate a full suite of nanoparticles (MNP, BNP, TNP)
+allomorph init-struct --stage all
+
+# Generate only monometallic nanoparticles
+allomorph init-struct --stage mnp
+
+# Generate bimetallic nanoparticles with visual check (ASE GUI)
+allomorph init-struct --stage bnp --vis
+```
+
+Check out the [basic demonstration](https://github.com/Jon-Ting/allomorph/blob/main/docs/demo.ipynb) notebook for further explanations and demonstrations!
+
+---
+
+## Features
+
+### Core Package Structure
+
+- `allomorph.init_struct` — Generation logic for monometallic, bimetallic, and trimetallic structures.
+- `allomorph.constants` — Physical constants, element properties, and global configuration.
+
+### Project Extras & Research Tools
+
+While the core `allomorph` package focuses on structure generation, this repository includes additional tools and legacy resources used in the original research pipeline:
+
+#### 1. Research Extras (`extras/`)
+These are standalone Python modules for managing the full simulation lifecycle:
+- `extras/eam/` — Creation of EAM alloy potential files.
+- `extras/md_sim/` — Management of LAMMPS simulations and HPC job submission.
+- `extras/feat_ext_eng/` — Integration with NCPac for structural feature extraction.
+
+#### 2. Physical Resources
+- **InitStruct**: LAMMPS and Bash scripts for alternative structure generation workflows.
+- **EAM**: Reference databases and tools for interatomic potentials.
+- **MDsim**: LAMMPS templates and scripts for simulation orchestration.
+- **FeatExtEng**: Source code and configuration for NCPac.
+
+### Degrees of Freedom
+
+AlloMorph supports a wide range of configurable parameters:
+
+- **Elemental composition:** Supports 1–3 arbitrary metallic elements (e.g., Au, Pt, Pd, Cu, Ni, Ag).
+- **Size:** Configurable diameter range (default: 10–30 Å).
+- **Shape:** CU (Cube), TH (Tetrahedron), RD (Rhombic Dodecahedron), OT (Octahedron), TO (Truncated Octahedron), CO (Cuboctahedron), DH (Decahedron), IC (Icosahedron), SP (Sphere).
+- **Ratio:** Arbitrary stoichiometric ratios (e.g., 20:40:40).
+- **Atomic ordering:**
+    - **BNP**: L10 (Ordered), RAL (Random), RCS (Random Core-Shell).
+    - **TNP**: L10R, CS, CL10S, CRALS, RRAL, CSRAL, CSL10, CRSR, LL10.
+
+### Future Enhancements
+
+- **Support >3 metals:** Extend logic to quadrimetallic and beyond.
+- **Non-FCC lattice support:** Support for BCC, HCP, and other lattices.
+- **Modern Formats:** Support for HDF5 and ASE trajectory outputs.
+
+## Documentation
+
+Detailed [documentations](https://allomorph.readthedocs.io/en/latest/) are hosted by `Read the Docs`.
+
+## Contributing
+
+`Sphractal` appreciates your enthusiasm and welcomes your expertise! 
+
+Please check out the [contributing guidelines](https://github.com/Jon-Ting/allomorph/blob/main/CONTRIBUTING.md) and 
+[code of conduct](https://github.com/Jon-Ting/allomorph/blob/main/CONDUCT.md). 
+By contributing to this project, you agree to abide by its terms.
+
+## License
+
+The project is distributed under an [MIT License](https://github.com/Jon-Ting/allomorph/blob/main/LICENSE).

allomorph-0.1.0/README.md

@@ -0,0 +1,109 @@
+# AlloMorph
+
+---
+
+## Description
+
+AlloMorph is a Python toolkit for generating initial structural models of monometallic, bimetallic, and trimetallic nanoparticles. It is designed to create large-scale datasets for atomistic simulations and machine learning applications.
+
+![](https://raw.githubusercontent.com/Jon-Ting/allmorph/main/docs/figs/TNPs_generation_flowchart.png)
+
+---
+
+## Installation
+
+This package uses [uv](https://docs.astral.sh/uv/) for dependency management and packaging. For detailed information on external tool requirements (LAMMPS, NCPac, etc.), see [DEPENDENCIES.md](DEPENDENCIES.md).
+
+```bash
+# Clone the repository
+git clone https://github.com/jonathan-ting/allomorph.git
+cd allomorph
+
+# Create a virtual environment and install dependencies
+uv venv
+uv pip install -e ".[dev]"
+```
+
+Alternatively, you can install directly with pip:
+
+```bash
+pip install allomorph
+```
+
+---
+
+## Usage
+
+The core `allomorph` command provides a streamlined interface for structure generation:
+
+```bash
+# Generate a full suite of nanoparticles (MNP, BNP, TNP)
+allomorph init-struct --stage all
+
+# Generate only monometallic nanoparticles
+allomorph init-struct --stage mnp
+
+# Generate bimetallic nanoparticles with visual check (ASE GUI)
+allomorph init-struct --stage bnp --vis
+```
+
+Check out the [basic demonstration](https://github.com/Jon-Ting/allomorph/blob/main/docs/demo.ipynb) notebook for further explanations and demonstrations!
+
+---
+
+## Features
+
+### Core Package Structure
+
+- `allomorph.init_struct` — Generation logic for monometallic, bimetallic, and trimetallic structures.
+- `allomorph.constants` — Physical constants, element properties, and global configuration.
+
+### Project Extras & Research Tools
+
+While the core `allomorph` package focuses on structure generation, this repository includes additional tools and legacy resources used in the original research pipeline:
+
+#### 1. Research Extras (`extras/`)
+These are standalone Python modules for managing the full simulation lifecycle:
+- `extras/eam/` — Creation of EAM alloy potential files.
+- `extras/md_sim/` — Management of LAMMPS simulations and HPC job submission.
+- `extras/feat_ext_eng/` — Integration with NCPac for structural feature extraction.
+
+#### 2. Physical Resources
+- **InitStruct**: LAMMPS and Bash scripts for alternative structure generation workflows.
+- **EAM**: Reference databases and tools for interatomic potentials.
+- **MDsim**: LAMMPS templates and scripts for simulation orchestration.
+- **FeatExtEng**: Source code and configuration for NCPac.
+
+### Degrees of Freedom
+
+AlloMorph supports a wide range of configurable parameters:
+
+- **Elemental composition:** Supports 1–3 arbitrary metallic elements (e.g., Au, Pt, Pd, Cu, Ni, Ag).
+- **Size:** Configurable diameter range (default: 10–30 Å).
+- **Shape:** CU (Cube), TH (Tetrahedron), RD (Rhombic Dodecahedron), OT (Octahedron), TO (Truncated Octahedron), CO (Cuboctahedron), DH (Decahedron), IC (Icosahedron), SP (Sphere).
+- **Ratio:** Arbitrary stoichiometric ratios (e.g., 20:40:40).
+- **Atomic ordering:**
+    - **BNP**: L10 (Ordered), RAL (Random), RCS (Random Core-Shell).
+    - **TNP**: L10R, CS, CL10S, CRALS, RRAL, CSRAL, CSL10, CRSR, LL10.
+
+### Future Enhancements
+
+- **Support >3 metals:** Extend logic to quadrimetallic and beyond.
+- **Non-FCC lattice support:** Support for BCC, HCP, and other lattices.
+- **Modern Formats:** Support for HDF5 and ASE trajectory outputs.
+
+## Documentation
+
+Detailed [documentations](https://allomorph.readthedocs.io/en/latest/) are hosted by `Read the Docs`.
+
+## Contributing
+
+`Sphractal` appreciates your enthusiasm and welcomes your expertise! 
+
+Please check out the [contributing guidelines](https://github.com/Jon-Ting/allomorph/blob/main/CONTRIBUTING.md) and 
+[code of conduct](https://github.com/Jon-Ting/allomorph/blob/main/CONDUCT.md). 
+By contributing to this project, you agree to abide by its terms.
+
+## License
+
+The project is distributed under an [MIT License](https://github.com/Jon-Ting/allomorph/blob/main/LICENSE).

allomorph-0.1.0/pyproject.toml

@@ -0,0 +1,101 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "allomorph"
+version = "0.1.0"
+description = "Toolkit for generating monometallic to trimetallic nanoparticle structural datasets for machine learning."
+
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [
+    { name = "Jonathan Yik Chang Ting" },
+]
+keywords = [
+    "nanoparticles",
+    "machine-learning",
+    "materials-science",
+    "LAMMPS",
+    "EAM",
+    "molecular-dynamics",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy",
+    "pandas",
+    "ase",
+    "scipy",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "ruff",
+    "sphinx",
+    "sphinx-rtd-theme",
+    "myst-parser",
+    "myst-nb",
+    "sphinx-autoapi",
+    "jupyterlab",
+    "python-semantic-release",
+]
+
+[project.scripts]
+allomorph = "allomorph.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jonathan-ting/allomorph"
+"Bug Tracker" = "https://github.com/jonathan-ting/allomorph/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/allomorph"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+preview = true
+
+[tool.semantic_release]
+version_toml = [
+    "pyproject.toml:project.version"
+]
+branch = "main"
+upload_to_pypi = true
+upload_to_release = true
+build_command = "pip install build && python -m build"

allomorph-0.1.0/src/allomorph/__init__.py

@@ -0,0 +1,58 @@
+"""Nanoparticle structure generation toolkit.
+
+A package for generating monometallic to trimetallic nanoparticle structural
+datasets for machine learning applications.
+"""
+
+__version__ = "0.1.0"
+
+from allomorph.constants import (
+    BNP_DIR,
+    BNP_DISTRIB_LIST,
+    DIAMETER_LIST,
+    ELE_DICT,
+    GOLDEN_RATIO,
+    LMP_DATA_DIR,
+    MNP_DIR,
+    RANDOM_DISTRIB_NO,
+    RATIO_LIST,
+    SHAPE_LIST,
+    TNP_DIR,
+    TNP_DISTRIB_LIST,
+    VACUUM_THICKNESS,
+    load_ele_dict_from_file,
+    parse_ele_comb,
+    validate_ele_dict,
+)
+from allomorph.init_struct.gen_bnp_al import gen_bnp, write_bnp
+from allomorph.init_struct.gen_bnp_cs import gen_hard_core_shell, write_hard_core_shell
+from allomorph.init_struct.gen_mnp import gen_mnp, write_mnp
+from allomorph.init_struct.gen_tnp_al import gen_tnp, write_tnp
+
+__all__ = [
+    "__version__",
+    "LMP_DATA_DIR",
+    "MNP_DIR",
+    "BNP_DIR",
+    "TNP_DIR",
+    "GOLDEN_RATIO",
+    "VACUUM_THICKNESS",
+    "RANDOM_DISTRIB_NO",
+    "ELE_DICT",
+    "DIAMETER_LIST",
+    "SHAPE_LIST",
+    "BNP_DISTRIB_LIST",
+    "TNP_DISTRIB_LIST",
+    "RATIO_LIST",
+    "validate_ele_dict",
+    "load_ele_dict_from_file",
+    "parse_ele_comb",
+    "gen_mnp",
+    "write_mnp",
+    "gen_bnp",
+    "write_bnp",
+    "gen_tnp",
+    "write_tnp",
+    "gen_hard_core_shell",
+    "write_hard_core_shell",
+]

allomorph-0.1.0/src/allomorph/__main__.py

@@ -0,0 +1,4 @@
+from allomorph.cli import main
+
+if __name__ == "__main__":
+    main()

allomorph-0.1.0/src/allomorph/cli.py

@@ -0,0 +1,85 @@
+"""Command-line interface for AlloMorph."""
+
+import argparse
+import sys
+
+from allomorph.constants import load_config, update_constants
+
+
+def main(argv=None):
+    """Entry point for the AlloMorph CLI."""
+    parser = argparse.ArgumentParser(
+        prog="allomorph",
+        description="Toolkit for generating monometallic to trimetallic nanoparticle structural datasets.",
+    )
+    parser.add_argument(
+        "--config",
+        help="Path to a configuration file (JSON, YAML, or TOML) to override default constants.",
+    )
+    
+    # Subcommands
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # init-struct subcommand (Main functionality)
+    init_parser = subparsers.add_parser(
+        "init-struct",
+        help="Generate initial nanoparticle structures.",
+    )
+    init_parser.add_argument(
+        "--stage",
+        choices=["mnp", "bnp", "tnp", "cs", "all"],
+        default="all",
+        help="Which structure generation stage to run (default: all)",
+    )
+    init_parser.add_argument(
+        "--replace",
+        action="store_true",
+        help="Overwrite existing files.",
+    )
+    init_parser.add_argument(
+        "--vis",
+        action="store_true",
+        help="Visualise generated structures (opens ASE GUI).",
+    )
+    init_parser.set_defaults(func=_init_struct_cmd)
+
+    args = parser.parse_args(argv)
+
+    if args.config:
+        config = load_config(args.config)
+        update_constants(config)
+
+    if args.vis:
+        print("Warning: --vis flag enabled. Visualization will run serially to prevent system hang.")
+        print("Many windows may be opened sequentially. Close one to see the next.")
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    args.func(args)
+
+
+def _init_struct_cmd(args):
+    """Run the initial structure generation command."""
+    from allomorph.init_struct.gen_bnp_al import main as gen_bnp_main
+    from allomorph.init_struct.gen_bnp_cs import write_hard_core_shell as gen_bnp_cs_main
+    from allomorph.init_struct.gen_mnp import main as gen_mnp_main
+    from allomorph.init_struct.gen_tnp_al import main as gen_tnp_main
+
+    if args.stage in ("mnp", "all"):
+        print("=== Generating monometallic nanoparticles (MNP) ===")
+        gen_mnp_main(replace=args.replace, vis=args.vis)
+    if args.stage in ("bnp", "all"):
+        print("=== Generating bimetallic nanoparticles (BNP) ===")
+        gen_bnp_main(replace=args.replace, vis=args.vis)
+    if args.stage in ("cs", "all"):
+        print("=== Generating hard core-shell nanoparticles (CS) ===")
+        gen_bnp_cs_main(replace=args.replace, vis=args.vis)
+    if args.stage in ("tnp", "all"):
+        print("=== Generating trimetallic nanoparticles (TNP) ===")
+        gen_tnp_main(replace=args.replace, vis=args.vis)
+
+
+if __name__ == "__main__":
+    main()