lineshape_tools 0.1.0__tar.gz → 0.1.2__tar.gz

{lineshape_tools-0.1.0 → lineshape_tools-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lineshape_tools
-Version: 0.1.0
+Version: 0.1.2
 Summary: Software to evaluate the optical lineshape function of a defect.
 Keywords: defect,luminescence,absorption,electron-phonon coupling,density functional theory
 Author-Email: "Mark E. Turiansky" <mark.e.turiansky.ctr@us.navy.mil>
@@ -38,6 +38,12 @@ Description-Content-Type: text/markdown
 In particular, it implements the approach pioneered by [Alkauskas *et al.*](https://doi.org/10.1088/1367-2630/16/7/073026) to compute the lineshape function within Huang-Rhys theory.
 The code interfaces with [`mace`](https://mace-docs.readthedocs.io/en/latest/) and [`phonopy`](https://phonopy.github.io/phonopy/) to evaluate the dynamical matrix and obtain the phonons of a defect-containing supercell.
 
+_Key Features_:
+ - Compute the temperature-dependent luminescence and absorption spectrum
+ - Compatible with phonons computed directly with Phonopy
+ - Accelerate evaluation of phonons with `mace` foundation models
+ - Convenience tools to fine-tune a `mace` foundation model to your specific system
+
 ### Installation
 <!-- install start -->
 To install the latest version of `lineshape_tools`, create a new virtual environment and run
@@ -45,33 +51,32 @@ To install the latest version of `lineshape_tools`, create a new virtual environ
 pip install lineshape_tools
 ```
 <!-- install end -->
-For more installation information and some performance considerations, see the [Installation page]().
+For more installation information and some performance considerations, see the [Installation page](https://lineshape-tools.readthedocs.io/en/latest/install.html).
 
 ### Usage 
 `lineshape_tools` provides a command-line interface for interacting with the code. See
 ```
 lineshape_tools --help
 ```
-Detailed usage information can be found in the [Tutorials page]().
+Detailed usage information can be found in the [Tutorials page](https://lineshape-tools.readthedocs.io/en/latest/tutorials.html).
 
 ### How to Cite
 <!-- cite start -->
 If you use this code, please consider citing
 ```bibtex
 @misc{turiansky_machine_2025,
-  title = {Machine Learning for Fast and Accurate Optical Lineshapes of Defects},
-  author = {Turiansky, Mark E. and Lyons, John L., and Bernstein, Noam},
+  title = {Machine Learning Phonon Spectra for Fast and Accurate Optical Lineshapes of Defects}, 
+  author = {Mark E. Turiansky and John L. Lyons and Noam Bernstein},
   year = {2025},
-  number = {arXiv:XXXX.XXXXX},
-  eprint = {XXXX.XXXXX},
-  primaryclass = {cond-mat},
-  publisher = {arXiv},
-  doi = {},
-  urldate = {},
+  number = {arXiv:2508.09113},
+  eprint = {2508.09113},
   archiveprefix = {arXiv},
+  primaryclass = {cond-mat.mtrl-sci},
+  doi = {10.48550/arXiv.2508.09113},
+  url = {https://arxiv.org/abs/2508.09113}, 
 }
 ```
 <!-- cite end -->
-Please also consider citing the foundational works that made this code possible on the [Citation page]().
+Please also consider citing the foundational works that made this code possible on the [Citation page](https://lineshape-tools.readthedocs.io/en/latest/cite.html).
 
 <!-- index end -->

{lineshape_tools-0.1.0 → lineshape_tools-0.1.2}/README.md

@@ -5,6 +5,12 @@
 In particular, it implements the approach pioneered by [Alkauskas *et al.*](https://doi.org/10.1088/1367-2630/16/7/073026) to compute the lineshape function within Huang-Rhys theory.
 The code interfaces with [`mace`](https://mace-docs.readthedocs.io/en/latest/) and [`phonopy`](https://phonopy.github.io/phonopy/) to evaluate the dynamical matrix and obtain the phonons of a defect-containing supercell.
 
+_Key Features_:
+ - Compute the temperature-dependent luminescence and absorption spectrum
+ - Compatible with phonons computed directly with Phonopy
+ - Accelerate evaluation of phonons with `mace` foundation models
+ - Convenience tools to fine-tune a `mace` foundation model to your specific system
+
 ### Installation
 <!-- install start -->
 To install the latest version of `lineshape_tools`, create a new virtual environment and run
@@ -12,33 +18,32 @@ To install the latest version of `lineshape_tools`, create a new virtual environ
 pip install lineshape_tools
 ```
 <!-- install end -->
-For more installation information and some performance considerations, see the [Installation page]().
+For more installation information and some performance considerations, see the [Installation page](https://lineshape-tools.readthedocs.io/en/latest/install.html).
 
 ### Usage 
 `lineshape_tools` provides a command-line interface for interacting with the code. See
 ```
 lineshape_tools --help
 ```
-Detailed usage information can be found in the [Tutorials page]().
+Detailed usage information can be found in the [Tutorials page](https://lineshape-tools.readthedocs.io/en/latest/tutorials.html).
 
 ### How to Cite
 <!-- cite start -->
 If you use this code, please consider citing
 ```bibtex
 @misc{turiansky_machine_2025,
-  title = {Machine Learning for Fast and Accurate Optical Lineshapes of Defects},
-  author = {Turiansky, Mark E. and Lyons, John L., and Bernstein, Noam},
+  title = {Machine Learning Phonon Spectra for Fast and Accurate Optical Lineshapes of Defects}, 
+  author = {Mark E. Turiansky and John L. Lyons and Noam Bernstein},
   year = {2025},
-  number = {arXiv:XXXX.XXXXX},
-  eprint = {XXXX.XXXXX},
-  primaryclass = {cond-mat},
-  publisher = {arXiv},
-  doi = {},
-  urldate = {},
+  number = {arXiv:2508.09113},
+  eprint = {2508.09113},
   archiveprefix = {arXiv},
+  primaryclass = {cond-mat.mtrl-sci},
+  doi = {10.48550/arXiv.2508.09113},
+  url = {https://arxiv.org/abs/2508.09113}, 
 }
 ```
 <!-- cite end -->
-Please also consider citing the foundational works that made this code possible on the [Citation page]().
+Please also consider citing the foundational works that made this code possible on the [Citation page](https://lineshape-tools.readthedocs.io/en/latest/cite.html).
 
 <!-- index end -->

{lineshape_tools-0.1.0 → lineshape_tools-0.1.2}/pyproject.toml

@@ -34,7 +34,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
 ]
-version = "0.1.0"
+version = "0.1.2"
 
 [project.license]
 text = "MIT"

{lineshape_tools-0.1.0 → lineshape_tools-0.1.2}/src/lineshape_tools/__init__.py

@@ -2,6 +2,6 @@
 
 __author__ = "Mark E. Turiansky"
 __email__ = "mark.e.turiansky.ctr@us.navy.mil"
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 __copyright__ = "Copyright (c) 2025 Mark E. Turiansky"
 __license__ = "MIT"

{lineshape_tools-0.1.0 → lineshape_tools-0.1.2}/src/lineshape_tools/cli.py

@@ -15,7 +15,7 @@ from cyclopts import Parameter
 from tqdm import tqdm
 
 from lineshape_tools.constants import omega2eV
-from lineshape_tools.lineshape import convert_A_to_L, gaussian, get_phonon_spec_func
+from lineshape_tools.lineshape import convert_A_to_L, gaussian, get_phonon_spec_func, get_Stot
 from lineshape_tools.phonon import get_disp_vect, get_ipr, get_phonons
 from lineshape_tools.plot import plot_spec_funcs
 
@@ -37,6 +37,7 @@ def collect(
     rtol: float = 1e-5,
     config_weight: float = 1.0,
     force_weighting: bool = False,
+    allow_constraint: bool = False,
 ) -> None:
     """Collect and process data for fine-tuning.
 
@@ -66,6 +67,8 @@ def collect(
         force_weighting (bool): store a config_weight that's inversely proportional to the max
             force that any atom feels in the configuration [min(0.02 / max_fpa, 1)]. Overwrites
             the value specified by config_weight.
+        allow_constraint (bool): allow constraints on atoms (e.g. selective dynamics) to modify the
+            forces. This is typically not desirable.
     """
     if strategy.lower() not in ("none", "qr", "dx"):
         raise ValueError("invalid strategy choice")
@@ -79,6 +82,10 @@ def collect(
         read_atoms = ase.io.read(fname, read_index)
         total_read += len(read_atoms)
         for atoms in tqdm(read_atoms, desc="[*] processing atoms", disable=len(read_atoms) < 10):
+            if len(atoms.constraints) > 0 and not allow_constraint:
+                logger.debug("atoms are constrained, removing prior to extracting forces")
+                atoms.set_constraint(None)
+
             forces = atoms.get_forces()
             if min_force < np.linalg.norm(forces, axis=1).max() < max_force:
                 atoms.info["REF_energy"] = atoms.get_potential_energy()
@@ -878,7 +885,11 @@ def compute_lineshape(
     fin_atoms: Atoms = ase.io.read(final)  # type:ignore[assignment]
 
     if dE is None:
-        dE = np.abs(fin_atoms.get_potential_energy() - ini_atoms.get_potential_energy())
+        try:
+            dE = np.abs(fin_atoms.get_potential_energy() - ini_atoms.get_potential_energy())
+        except RuntimeError:
+            logger.critical("input files do not contain total energy, so dE cannot be determined")
+            raise
         logger.info(f"energy difference not provided, found dE = {dE} from input structures")
 
     sqrt_mass = np.repeat(np.sqrt(fin_atoms.get_masses()), 3)
@@ -902,6 +913,8 @@ def compute_lineshape(
     omega, U = get_phonons(H)
     dq_k = U.T @ dq
 
+    logger.info(f"total Huang-Rhys factor Stot={get_Stot(dq_k, omega):.04f}")
+
     if gamma_psb is not None:
         logger.info("computing inverse participation ratios")
         ipr, ipr_cut, gamma_lvm = get_ipr(U), gamma_psb[0], gamma_psb[1]