vestacrystparser 0.1.0__tar.gz

vestacrystparser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bernard Field, Musa Hussein
+
+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.

vestacrystparser-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: vestacrystparser
+Version: 0.1.0
+Summary: Parser for VESTA crystal structure visualisation files.
+Author-email: Bernard Field <bfield@lbl.gov>, Musa Hussein <mhussein@lbl.gov>
+Maintainer-email: Bernard Field <bfield@lbl.gov>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Griffin-Group/vestacrystparser
+Project-URL: Documentation, https://griffin-group.github.io/vestacrystparser/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: File Formats
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pymatgen
+Requires-Dist: pymatgen; extra == "pymatgen"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: autopep8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: myst-parser; extra == "dev"
+Dynamic: license-file
+
+# vestacrystparser
+
+**vestacrystparser** is an unofficial general-purpose Python parser for
+[VESTA](https://jp-minerals.org/vesta/) crystal visualisation files.
+It provides a programmatic API for creating and modifying VESTA files.
+It is intended to enable batch-creating consistent visualisation states,
+removing the tedium of manually adjusting settings via the GUI.
+
+This project is functional, but feature-incomplete.
+High-level API for modifying specific parts of the file in specific ways are
+implemented as needed or requested.
+Pull requests adding more methods are welcome.
+However, the low-level API can cover all cases, albeit requiring more care.
+
+See the [documentation](https://griffin-group.github.io/vestacrystparser/)
+for instructions for installation and usage.
+
+**vestacrystparser** is made available under the MIT License (see `LICENSE`
+file).

vestacrystparser-0.1.0/README.md

@@ -0,0 +1,19 @@
+# vestacrystparser
+
+**vestacrystparser** is an unofficial general-purpose Python parser for
+[VESTA](https://jp-minerals.org/vesta/) crystal visualisation files.
+It provides a programmatic API for creating and modifying VESTA files.
+It is intended to enable batch-creating consistent visualisation states,
+removing the tedium of manually adjusting settings via the GUI.
+
+This project is functional, but feature-incomplete.
+High-level API for modifying specific parts of the file in specific ways are
+implemented as needed or requested.
+Pull requests adding more methods are welcome.
+However, the low-level API can cover all cases, albeit requiring more care.
+
+See the [documentation](https://griffin-group.github.io/vestacrystparser/)
+for instructions for installation and usage.
+
+**vestacrystparser** is made available under the MIT License (see `LICENSE`
+file).

vestacrystparser-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools >= 80.0", "setuptools_scm[simple] >= 8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vestacrystparser"
+#version = "0.0.1a1"
+dynamic = ["version"]
+dependencies = [
+]
+requires-python = ">= 3.9"
+authors = [
+    {name = "Bernard Field", email = "bfield@lbl.gov"},
+    {name = "Musa Hussein", email = "mhussein@lbl.gov"}
+]
+maintainers = [
+    {name = "Bernard Field", email = "bfield@lbl.gov"}
+]
+description = "Parser for VESTA crystal structure visualisation files."
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Natural Language :: English",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Topic :: File Formats",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.optional-dependencies]
+pymatgen = ["pymatgen"]
+dev = [
+    "pytest",
+    "flake8",
+    "autopep8",
+    "pytest-cov",
+    "sphinx",
+    "myst-parser",
+]
+
+[project.urls]
+Repository = "https://github.com/Griffin-Group/vestacrystparser"
+Documentation = "https://griffin-group.github.io/vestacrystparser/"
+

vestacrystparser-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vestacrystparser-0.1.0/vestacrystparser/__init__.py

@@ -0,0 +1 @@
+from vestacrystparser.parser import VestaFile

vestacrystparser-0.1.0/vestacrystparser/convert.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+# Copyright 2025 Bernard Field
+"""Create VESTA files from structural data files (POSCAR, etc.).
+"""
+
+from pymatgen.core import Structure
+from pymatgen.io.vasp.inputs import Poscar
+
+from vestacrystparser.parser import VestaFile
+
+
+def vesta_from_structure(stru: Structure) -> VestaFile:
+    """Return a VestaFile from pymatgen.core.Structure"""
+    # TODO Convert numpy floats to regular floats.
+    # Initialise an empty Vesta file
+    vfile = VestaFile()
+    # Set the lattice parameters.
+    vfile.set_cell(*stru.lattice.abc, *stru.lattice.angles)
+    # Add the sites
+    counts = {}
+    for site in stru:
+        element = site.specie.symbol
+        # When loading POSCAR, site labels in VESTA are numbered.
+        if element in counts:
+            counts[element] += 1
+        else:
+            counts[element] = 1
+        vfile.add_site(element, element+str(counts[element]),
+                       *site.frac_coords,
+                       add_bonds=True)
+    # Sort SBOND
+    vfile.sort_bonds()
+    # Done
+    return vfile
+
+
+def vesta_from_poscar(fname: str) -> VestaFile:
+    """Return a VestaFile from a POSCAR file at fname"""
+    # Load the POSCAR
+    pos = Poscar.from_file(fname)
+    # Create a VestaFile from the structure
+    vfile = vesta_from_structure(pos.structure)
+    # Set the title
+    vfile.title = pos.comment
+    return vfile
+
+# Thoughts...
+# CIF will be tricky, because it contains symmetry and precision
+# information and is variable in the data it contains, so I can't simply
+# convert to Structure then use that.
+# pymatgen.io.cif supports reading CIF files with all data.
+# If pymatgen proves unreliable, could also attempt PyCifRW https://pypi.org/project/PyCifRW/
+# In any case, CIF is hard, and I don't have much experience with CIF's.

vestacrystparser-0.1.0/vestacrystparser/export.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+# Copyright 2025 Bernard Field
+"""Open VESTA and export images.
+
+:func:`export_image_from_file` is the core function,
+which directly opens a VESTA file then exports an image file
+using VESTA's (rather sparse) command line interface.
+
+This requires a working VESTA installation on your system.
+"""
+
+import platform
+import os
+import subprocess
+import time
+
+
+class NoVestaError(OSError):
+    """VESTA does not exist or cannot be found."""
+    pass
+
+
+def export_image_from_file(input: str, output: str, scale: int = 1,
+                           close: bool = True, block: bool = True,
+                           timeout: float = None):
+    """Opens a file in VESTA and saves it as an image.
+
+    You can open VESTA before running this command to set the size of the
+    window, which determines the size of the image.
+
+    Runs ASYNCHRONOUSLY. May be subject to race conditions.
+    Modifying the files while running this command will
+    cause unexpected behaviour. I do not know how to retrieve an exit call,
+    besides checking if `output` has been written (which is what `block` does).
+
+    Note that, even with the `close` argument, VESTA will remain open after
+    this call. (`close` just closes the tab within VESTA.) You are 
+    responsible for closing it yourself when you're done.
+
+    `block` is strongly recommended if you are doing more than a couple
+    at once, because I've found VESTA will max-out on processes if it
+    tries to open too many files simultaneously.
+
+    VESTA has a command line interface:
+    https://jp-minerals.org/vesta/en/doc/VESTAch17.html
+
+    Koichi Momma gives directions on how to use VESTA's command line interface:
+    https://groups.google.com/g/vesta-discuss/c/xePcwJ3Mdgw/m/GyC8_UZbAwAJ
+
+    Args:
+        input: Path to file readable by VESTA.
+        output: Path to write image to. Should include a recognisable image
+            file extension.
+        scale: Amount to scale raster image by.
+        close: Whether to close the VESTA tab afterward.
+        block: Whether to block the main process until the file is written.
+            If the export process fails on VESTA's end, then this will hang!
+            However, it is recommended to reduce race conditions or system
+            overload.
+        timeout: Number of seconds to block for until we raise TimeoutError.
+            If None, will count indefinitely.
+            Note, though, that VESTA will still be running if we hit the
+            Timeout. We just hand the focus back to Python.
+
+    Raises:
+        NoVestaError: If fails to run VESTA.
+        OSError: If run on an unsupport OS.
+            (Supports Windows, Linux, MacOS/Darwin.)
+        FileNotFoundError: If `input` doesn't exist or `output`'s directory
+            doesn't exist.
+        TimeoutError: block=True and we timeout.
+    """
+    # First, identify which platform we are on.
+    opsys = platform.system()
+    # This determines the form of the VESTA command
+    if opsys == "Darwin":  # a.k.a. MacOS
+        vesta_cmd = ["open", "-n", "-a", "VESTA.app", "--args"]
+    elif opsys == "Windows" or opsys == "Linux":
+        vesta_cmd = ["VESTA"]
+    else:
+        # If we're here, then python platform has dones something wrong.
+        raise OSError(f"Unrecognised operating system {opsys}.")
+    # Next, identify the absolute path to the input,
+    # as my tests on MacOS have found that we must specify the absolute path
+    # or else it will do the path from /Applications/VESTA
+    abs_input = os.path.abspath(input)
+    # Validate that the file exists.
+    if not os.path.isfile(abs_input):
+        raise FileNotFoundError(f"Cannot find file {abs_input}.")
+    # Sanitise scale
+    if not isinstance(scale, int):
+        scale = int(scale)
+    # Validate that output directory exists.
+    output_dir = os.path.dirname(output)
+    if output_dir and not os.path.isdir(output_dir):
+        # output_dir may be an empty string if output has no path.
+        # That is acceptable, but isdir would say False.
+        # So only check if the directory doesn't exist if non-empty.
+        raise FileNotFoundError(f"Cannot find directory {output_dir}.")
+    # Prepare current state for blocking.
+    if block:
+        # If the file exists, we'll check when it gets overwritten.
+        if os.path.exists(output):
+            old_time = os.path.getmtime(output)
+        else:
+            # Otherwise, we'll check when it gets written.
+            old_time = None
+    # Form the command to execute.
+    cmd = vesta_cmd + ["-open", abs_input,
+                       "-export_img", f"scale={scale}", str(output)]
+    if close:
+        cmd += ["-close"]
+    # Run
+    try:
+        subprocess.run(cmd, capture_output=True, text=True, check=True)
+    except subprocess.CalledProcessError as e:
+        # MacOS gave the following stderr:
+        #   Unable to find application named 'VESTA.app'\n
+        # But there might be other reasons this fails, or platform
+        # dependencies.
+        raise NoVestaError("Failed to run VESTA.")
+    except FileNotFoundError:
+        # I find that Mac and Linux will give FileNotFoundError if the
+        # specified command does not exist.
+        raise NoVestaError("Failed to run VESTA.")
+    if block:
+        elapsed = 0
+        increment = 0.02
+        if old_time is None:
+            # Check if the file has been created.
+            while not os.path.exists(output) and \
+                    (timeout is None or elapsed < timeout):
+                time.sleep(increment)
+                elapsed += increment
+        else:
+            # Check if the file has been overwritten.
+            while os.path.getmtime(output) == old_time and \
+                    (timeout is None or elapsed < timeout):
+                time.sleep(increment)
+                elapsed += increment
+        if timeout is not None and elapsed >= timeout:
+            raise TimeoutError(
+                f"export_image_from_file timed out after {elapsed} seconds.")