Metadata-Version: 2.4
Name: pyNanoMatBuilder
Version: 0.16.0
Summary: Build and visualize complex crystalline nanoparticle architectures, including models on substrates, for materials science, X-ray data analysis, and electron microscopy research
Author-email: "Sara Mokhtari, LPCNO" <smokhtari@insa-toulouse.fr>, "Romuald Poteau, LPCNO" <romuald.poteau@utoulouse.fr>
License: GPL-3.0-or-later
Project-URL: Repository, https://github.com/rpoteau/pynanomatbuilder
Project-URL: Changelog, https://github.com/rpoteau/pynanomatbuilder/blob/main/ChangeLog.md
Project-URL: Documentation, https://pynanomatbuilder.readthedocs.io/en/latest/
Project-URL: Issues, https://github.com/rpoteau/pynanomatbuilder/issues
Project-URL: Try on Colab, https://colab.research.google.com/github/rpoteau/pyNanoMatBuilder/blob/main/pyNMB-examples.ipynb
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase
Requires-Dist: imageio[ffmpeg]
Requires-Dist: ipython
Requires-Dist: ipywidgets
Requires-Dist: jupyter
Requires-Dist: matplotlib
Requires-Dist: mendeleev
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: plotly
Requires-Dist: pubchempy
Requires-Dist: py3Dmol
Requires-Dist: pymatgen
Requires-Dist: scipy
Requires-Dist: seaborn
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: pandoc; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Provides-Extra: debye
Requires-Dist: debyecalculator; extra == "debye"
Provides-Extra: tem
Requires-Dist: abtem; extra == "tem"
Provides-Extra: visu
Requires-Dist: tools4pyphyschem; extra == "visu"
Dynamic: license-file

<div style="text-align:center">
<img src="https://raw.githubusercontent.com/rpoteau/pynanomatbuilder/main/pyNanoMatBuilder/resources/svg/pyNanoMatBuilder_banner.png" alt="pyNMB_banner" width="800" />
</div>
<br>

Most **nanoparticles** have a well-defined shape. The habit of a crystalline nanoparticle is dependent on its crystallographic form and growth conditions. Its properties depends on its size, shape, surface topology and composition, etc... Modeling nanoparticles at the atomic scale is a crucial preliminary step to evaluate their potential for various applications. However, the process of generating an initial conformation for modeling and simulation is not that easy. Several tools are already available, including in the python realm. But to the best of our knowledge, they do not give access to the fascinating diversity of shapes encountered at the nanoscale. `pyNanoMatBuilder` is a new python tool designed to create nanoparticle models from **any crystal structure** or atomically precise structures, *i.e.* **magic numbers polyhedra**.

Once a nanoparticle is built, `pyNanoMatBuilder` provides a complete toolkit
for **atomic-precision shape engineering**, organized in six families:

| Family | Key functions |
|--------|--------------|
| Planar sculpting | `applySlicing`, `remove_plane` |
| Volume clipping | `clip_to_sphere`, `clip_to_cylinder`, `clip_to_ellipsoid`, `clip_to_cone` |
| Tip shaping | `round_tip_in_direction`, `align_to_plane` |
| Surface peeling | `peel_by_coordination`, `peel_by_shifted_ellipsoid` |
| Symmetry & assembly | `apply_rotation`, `apply_reflection`, `replicate_by_rotation`, `replicate_by_reflection`, `applyTwist` |
| Construction Solid Geometry | `cut_by`, `union_with`, `intersect_with`, `flush_inlay_with` |

---

**What can you build?**

Various atomic ordered arrangements can be obtained by instantiating specific classes:

- **`crystalNPs`** builds crystal-based shapes — **spheres**, **cubes**,
  **ellipsoids**, **cylinders**, **parallelepipeds**, and more generally any
  **Wulff construction**. Users can upload any CIF file or use the built-in
  database. Pre-defined Wulff shapes are available, and custom Miller indices
  with surface energies can be specified. This works for any Bravais lattice.

- **`platonicNPs`**, **`archimedeanNPs`**, **`catalanNPs`** and **`johnsonNPs`**
  generate atomically precise polyhedra such as **icosahedra**, **decahedra**
  and many other five-fold structures that Wulff constructions cannot produce.

- the **shape engineering** tools can be combined to build complex morphologies that go well
    beyond simple convex shapes, including **pentatwinned nanorods** (bipyramids,
    walled bipyramids, double cones, rods, ellipsoids, capsules), **concave
    nanoparticles** (nanostars, octopods), or any user-defined custom geometry.

The crystal habits of the structures generated by `pyNanoMatBuilder` are
summarized below:

<span style="display:block;text-align:center">
<img width="1200px" src="https://raw.githubusercontent.com/rpoteau/pynanomatbuilder/main/pyNanoMatBuilder/resources/figs/pnmbAvailableStructures.png"/>
</span>


---

**Installation**

Activate your python environment and run:

```bash
pip install pyNanoMatBuilder
```

---

**Quick usage**

Let's first make a sphere with a diameter of ~ 4 nm. This is the target size, but the measured size will be slightly different due to compound cristalline organization. 

```python
from pyNanoMatBuilder import crystalNPs as cyNP
from pyNanoMatBuilder import utils as pyNMBu

# Define parameters
sphere_diameter = [4] # Target diameter in nm
# Instantiate the Crystal object (Au fcc sphere)
AuNP = cyNP.Crystal(
    "Au fcc",
    size=sphere_diameter, 
    shape="sphere", 
    thresholdCoreSurface=1, 
    skipSymmetryAnalyzis=False, 
    noOutput=False
)

# Save the results in various formats
# The 'write' utility automatically creates the 'coords/' directory, if it does not exist
pyNMBu.write("coords/SphericalAuNP.xyz", AuNP.NP)                # Main coordinates
pyNMBu.write("coords/SphericalAuNP_CoreSurface.xyz", AuNP.NPcs)  # Core/surface model
pyNMBu.write("coords/SphericalAuNP.script", AuNP.jMolCS)         # JMOL visualization script

# Save unitcells
pyNMBu.write("coords/SphericalAuNP_uc.cif", AuNP.cif)            # The base unitcell
pyNMBu.write("coords/SphericalAuNP_sc.cif", AuNP.sc)             # The supercell used for shaping
```

---
See more explanations in the **How to? Workflow Guides** section of the Main Tutorial notebook 

**Main Tutorial**: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/rpoteau/pynanomatbuilder/blob/main/pyNMB-examples.ipynb)

---

[![PyPI version](https://img.shields.io/pypi/v/pynanomatbuilder.svg)](https://pypi.org/project/pynanomatbuilder/)
[![Documentation Status](https://readthedocs.org/projects/pynanomatbuilder/badge/?version=latest)](https://pynanomatbuilder.readthedocs.io/en/latest/?badge=latest)
[![License](https://img.shields.io/github/license/rpoteau/pynanomatbuilder)](https://github.com/rpoteau/pynanomatbuilder/blob/main/LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/pynanomatbuilder)](https://pypi.org/project/pynanomatbuilder/)
<!-- [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18644730.svg)](https://doi.org/10.5281/zenodo.18644730) -->

