virp 1.0.0__tar.gz

virp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kedar Hippalgaonkar's Materials by Design Lab
+
+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.

virp-1.0.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.2
+Name: virp
+Version: 1.0.0
+Summary: VIRtual cell generation by Permutation
+Author-email: Andy Paul Chen <la.vache.qui.vit@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Kedar Hippalgaonkar's Materials by Design Lab
+        
+        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.
+        
+Keywords: disordered,virtual cell,cif,partial occupancy
+Classifier: Programming Language :: Python :: 3.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymatgen
+Requires-Dist: chgnet
+Requires-Dist: matgl==1.0.0
+Requires-Dist: dgl==1.1.2
+Requires-Dist: poshcar
+
+<img src="graphics/virpbanner.png" width="870">
+
+# `virp`: VIRtual cell generation by Permutation
+ `virp` is a code for the fast generation of a virtual cell from a crystal structure (in CIF format) containing site disorder. It is named after Singapore's first superhero, VR Man, whose superpower is "Virping". The show was a flop, but we are still proud of him. 
+ 
+ This project is inspired by the `Supercell` code of Okhotnikov, Charpentier and Cadars (<i>J. Cheminform. <b>8</b>, 17</i>), which formed the basis of our fast virtual cell generation algorithm, as well as the `aflow++` framework (<i>Comput. Mater. Sci. <b>217</b>, 111889</i>), for the statistical postprocessing of materials properties.
+
+ ## Theory
+ (To be updated!)
+
+ ## Requirements
+`pymatgen`, `chgnet`, and `matgl` (`matgl==1.0.0`; `dgl==1.1.2`)<br>
+ __Optional__: You can also use git for the fancy installation. Otherwise, downloading the .py file will do.
+
+ ## Installation
+ `pip install git+https://github.com/andypaulchen/virp.git`<br>
+ Update to latest release: uninstall and re-install
+
+ ## Building a database
+ The root directory has a folder (`session`) which holds the python scripts which build a library of virtual cells (`generate.py`) and postprocessing scripts (`connectivity.py` and `properties.py`). After each script is run, the results are saved as `.csv` files.
+
+ 1. To prepare for a session, copy the `session` folder in your workspace and place the `.cif` files you want to process (make virtual cells + postprocessing) in the subfolder `_disordered_cifs`. Feel free to rename `session` folder to something more identifiable
+
+ 2. Run `generate.py` to create a supercell and (by default) 400 virtual cells.
+    - after this step, a structure subfolder (e.g. `structure`) is created in `session` for each `structure.cif` file in `_disordered_cifs`, with the same name. Inside this folder is a supercell CIF and folders for structure-optimized (`stropt`) and non-structure-optimized virtual cells (`no_stropt`). The details of this run is recorded in `virp_session_summary.csv`.
+
+ 3. Run `connectivity.py` for atomic connectivity post-processing
+    - after this step, the results are written to `connectivity.csv` and `scatterplot.png` under `stropt` and `no_stropt`.
+
+ 4. Run `properties.py` to predict materials properties. This is performed on `stropt` subfolders only.
+    - after this step, the results are written to `virtual_properties.csv` in the `structure` subfolder.
+
+ In summary, this is what a session looks like after all three routines have completed:
+
+ <img src="graphics/operation.png" width="870">
+
+ ## Versions and changelog
+ `v0.1.1`: first workable code, with function to generate a virtual cell. <br>
+ `v0.2.1`: added enumeration function <br>
+ `v0.2.2`: enumeration can be imported now (fix) <br>
+ `v0.3.0`: you can now make a batch of virtual cells<br>
+ `v0.4.3`: added tools to build a database
+
+ ## Debugging and support
+ The `virp` code has been tested on a limited number of platforms, so far Windows and Linux. If you are running into any problems during operation, please hound me (Andy Paul Chen) at la.vache.qui.vit(at)gmail.com, and I will try my best to help.
+ 

virp-1.0.0/README.md

@@ -0,0 +1,46 @@
+<img src="graphics/virpbanner.png" width="870">
+
+# `virp`: VIRtual cell generation by Permutation
+ `virp` is a code for the fast generation of a virtual cell from a crystal structure (in CIF format) containing site disorder. It is named after Singapore's first superhero, VR Man, whose superpower is "Virping". The show was a flop, but we are still proud of him. 
+ 
+ This project is inspired by the `Supercell` code of Okhotnikov, Charpentier and Cadars (<i>J. Cheminform. <b>8</b>, 17</i>), which formed the basis of our fast virtual cell generation algorithm, as well as the `aflow++` framework (<i>Comput. Mater. Sci. <b>217</b>, 111889</i>), for the statistical postprocessing of materials properties.
+
+ ## Theory
+ (To be updated!)
+
+ ## Requirements
+`pymatgen`, `chgnet`, and `matgl` (`matgl==1.0.0`; `dgl==1.1.2`)<br>
+ __Optional__: You can also use git for the fancy installation. Otherwise, downloading the .py file will do.
+
+ ## Installation
+ `pip install git+https://github.com/andypaulchen/virp.git`<br>
+ Update to latest release: uninstall and re-install
+
+ ## Building a database
+ The root directory has a folder (`session`) which holds the python scripts which build a library of virtual cells (`generate.py`) and postprocessing scripts (`connectivity.py` and `properties.py`). After each script is run, the results are saved as `.csv` files.
+
+ 1. To prepare for a session, copy the `session` folder in your workspace and place the `.cif` files you want to process (make virtual cells + postprocessing) in the subfolder `_disordered_cifs`. Feel free to rename `session` folder to something more identifiable
+
+ 2. Run `generate.py` to create a supercell and (by default) 400 virtual cells.
+    - after this step, a structure subfolder (e.g. `structure`) is created in `session` for each `structure.cif` file in `_disordered_cifs`, with the same name. Inside this folder is a supercell CIF and folders for structure-optimized (`stropt`) and non-structure-optimized virtual cells (`no_stropt`). The details of this run is recorded in `virp_session_summary.csv`.
+
+ 3. Run `connectivity.py` for atomic connectivity post-processing
+    - after this step, the results are written to `connectivity.csv` and `scatterplot.png` under `stropt` and `no_stropt`.
+
+ 4. Run `properties.py` to predict materials properties. This is performed on `stropt` subfolders only.
+    - after this step, the results are written to `virtual_properties.csv` in the `structure` subfolder.
+
+ In summary, this is what a session looks like after all three routines have completed:
+
+ <img src="graphics/operation.png" width="870">
+
+ ## Versions and changelog
+ `v0.1.1`: first workable code, with function to generate a virtual cell. <br>
+ `v0.2.1`: added enumeration function <br>
+ `v0.2.2`: enumeration can be imported now (fix) <br>
+ `v0.3.0`: you can now make a batch of virtual cells<br>
+ `v0.4.3`: added tools to build a database
+
+ ## Debugging and support
+ The `virp` code has been tested on a limited number of platforms, so far Windows and Linux. If you are running into any problems during operation, please hound me (Andy Paul Chen) at la.vache.qui.vit(at)gmail.com, and I will try my best to help.
+ 

virp-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel", "pip<24.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "virp"
+version = "1.0.0"
+description = "VIRtual cell generation by Permutation"
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Andy Paul Chen", email = "la.vache.qui.vit@gmail.com"}
+]
+dependencies = [
+    "pymatgen",
+    "chgnet",
+    "matgl==1.0.0",
+    "dgl==1.1.2",
+    "poshcar"
+]
+keywords = [
+    "disordered", 
+    "virtual cell", 
+    "cif", 
+    "partial occupancy"
+]
+classifiers = [
+    "Programming Language :: Python :: 3.9",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]

virp-1.0.0/setup.cfg

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

virp-1.0.0/setup.py

@@ -0,0 +1,14 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="virp",
+    version="1.0.0",
+    packages=find_packages(),
+    install_requires=[
+        "pymatgen",
+        "chgnet",
+        "matgl==1.0.0",
+        "dgl==1.1.2",
+        "poshcar"
+    ],
+)

virp-1.0.0/virp/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2024, Kedar Hippalgaonkar's Materials by Design Lab
+# Distributed under the terms of the MIT License.
+
+"""
+Virp (VIRtual cell generation by Permutation) is a code for generating a virtual cell from a site-disordered .cif crystal file
+"""
+
+from .main import *
+from .enumerate import *
+
+__copyright__  = "Kedar Hippalgaonkar's Materials by Design Lab"
+__version__    =  "1.0.0"
+__maintainer__ = "Andy Paul Chen"
+__email__      = "la.vache.qui.vit@gmail.com"
+__status__     = "Development"
+__date__       = "10 October 2024"

virp-1.0.0/virp/database.py

@@ -0,0 +1,113 @@
+# database.py
+
+# External Imports
+from pymatgen.io.cif import CifParser # write pymatgen structure to cif
+from pathlib import Path
+from tqdm import tqdm
+import os
+
+def DisorderQuery(folder_path):
+    """
+    Process all CIF files in a folder to check for partial occupancy.
+    Displays a progress bar and summary statistics.
+    
+    Parameters:
+    -----------
+    folder_path : str
+        Path to the folder containing CIF files
+    threshold : float, optional
+        Occupancy threshold for checking partial occupancy
+    
+    Returns:
+    --------
+    dict
+        Dictionary with CIF filenames as keys and their analysis results as values
+    """
+    folder = Path(folder_path)
+    
+    if not folder.is_dir():
+        raise NotADirectoryError(f"Folder not found: {folder_path}")
+    
+    results = {}
+    cif_files = list(folder.glob("*.cif"))
+    
+    # Initialize counters
+    total_files = len(cif_files)
+    files_with_partial = 0
+    files_without_partial = 0
+    error_files = 0
+    
+    # Process each CIF file with progress bar
+    for cif_file in tqdm(cif_files, desc="Processing CIF files", unit="file"):
+        try:
+            result = is_site_disordered(str(cif_file))
+            results[cif_file.name] = result
+            
+            # Update counters silently
+            if result["has_partial"]:
+                files_with_partial += 1
+            else:
+                files_without_partial += 1
+                
+        except Exception as e:
+            error_files += 1
+            results[cif_file.name] = {"error": str(e)}
+    
+    # Print final summary statistics
+    print("\nSummary Statistics:")
+    print("-" * 50)
+    print(f"Total CIF files processed: {total_files}")
+    print(f"Files with partial occupancy: {files_with_partial} ({files_with_partial/total_files*100:.1f}%)")
+    print(f"Files without partial occupancy: {files_without_partial} ({files_without_partial/total_files*100:.1f}%)")
+    if error_files > 0:
+        print(f"Files with errors: {error_files} ({error_files/total_files*100:.1f}%)")
+    
+    return results
+
+
+
+def is_SiteDisordered(cif_path):
+    """
+    Check if a CIF file contains sites with partial occupancy.
+    
+    Parameters:
+    -----------
+    cif_path : str
+        Path to the CIF file
+    threshold : float, optional
+        Occupancy threshold below which a site is considered partially occupied
+        Default is 1.0 (fully occupied)
+    
+    Returns:
+    --------
+    dict
+        Dictionary containing:
+        - has_partial: bool, whether partial occupancy was found
+        - partial_sites: list of tuples (site index, species, occupancy)
+    """
+    # Verify file exists
+    if not os.path.exists(cif_path):
+        raise FileNotFoundError(f"CIF file not found: {cif_path}")
+    
+    # Parse the CIF file
+    parser = CifParser(cif_path)
+    structure = parser.get_structures()[0]
+    
+    # Initialize results
+    partial_sites = []
+    
+    # Check each site in the structure
+    for i, site in enumerate(structure.sites):
+        species_dict = site.species.as_dict()
+        
+        # Check occupancy for each species on the site
+        for element, occupancy in species_dict.items():
+            if occupancy < 1.0:
+                partial_sites.append((i, element, occupancy))
+    
+    result = {
+        "has_partial": len(partial_sites) > 0,
+        "partial_sites": partial_sites
+    }
+    
+    return result

virp-1.0.0/virp/enumerate.py

@@ -0,0 +1,160 @@
+# enumerate.py: counts possible permutations and combinations for atom filling in disordered sites
+
+from itertools import product
+from math import factorial, prod
+import numpy as np
+import re
+
+def format_integer(num, prec = 6):
+    return np.format_float_scientific(num, precision=prec) if num >= 10**prec else str(num)
+
+
+def discretize_floats(arr):
+    # Store possible discretizations for each float
+    discretizations = []
+    
+    for num in arr:
+        if num % 1 == 0.5:  # Equidistant case
+            lower = int(num // 1)  # Round down
+            upper = lower + 1      # Round up
+            discretizations.append([lower, upper])
+        else:
+            discretizations.append([round(num)])  # Standard rounding
+    
+    # Generate all combinations of discretizations
+    all_discretizations = [list(discretization) for discretization in product(*discretizations)]
+    
+    return all_discretizations
+    
+
+def remove_duplicate_sublists(lst):
+    seen = set()
+    unique_sublists = []
+    for sublist in lst:
+        sublist_tuple = tuple(sublist)
+        if sublist_tuple not in seen:
+            seen.add(sublist_tuple)
+            unique_sublists.append(sublist)
+    return unique_sublists
+
+
+def enumerate_site(N, compositions, verbose = True):
+    # Enumerate combination of enumerations by disordered site
+    # N: number of sites
+    # compositions: [float], partition fractions adding up to < 1
+    if sum(compositions) > 1: print("Error: Compositions add up to more than 100%: ", compositions) # This no make sense (failsafe)
+    else:
+        if sum(compositions) < 1: compositions.append(1-sum(compositions)) # include vacancies in permutation
+        partitions = []
+        for i in range(len(compositions)):
+            partitions.append(sum(compositions[:i+1]))
+        partN = [i*N for i in partitions]
+        
+        # initialize snapping
+        total_combinations = factorial(N)
+        if verbose: print("- Raw permutations: ", format_integer(total_combinations), "(", N, "!)")
+
+        # discretize floats
+        all_snaps = discretize_floats(partN)
+        # assign at least 1 atom per element
+        for snap in all_snaps:
+            for index in range(len(snap)):
+                if index > 0:
+                    if snap[index] == snap[index-1]:
+                        if verbose and (snap[index] + 1 >= N): print("Error: Choose a bigger supercell!")
+                        else: snap[index] += 1
+        # remove duplicates in all_snaps
+        all_snaps = remove_duplicate_sublists(all_snaps)
+
+        # for each snap, calculate number of combinations
+        allcombinations = 0
+        for snap in all_snaps:
+            if verbose: print("- Snap: ", snap)
+            combination = total_combinations
+            for index in range(len(snap)):
+                if index == 0: n = snap[index]
+                else: n = snap[index]-snap[index-1]
+                combination /= factorial(n)
+            thiscombination = int(combination)
+            allcombinations += thiscombination
+            if verbose: print("- No. of combinations: ", format_integer(thiscombination)) 
+
+        return all_snaps, allcombinations
+    
+
+def get_site_combination(edit_block, edit_name):
+    # Auxiliary function which, outside of the enumerate structure routine, will make no sense whatsoever
+
+    # 1. What are the unique elements and occupancies?
+    atomoccpairslist = []
+    for evalline in edit_block:
+        # Split each line into components (using split will automatically handle whitespaces)
+        parts = evalline.split()
+        atomoccpair = (parts[0], float(parts[-1]))
+        if atomoccpair not in atomoccpairslist:
+            atomoccpairslist.append(atomoccpair)
+
+    # Display specifications
+    print("Disordered site name: ", edit_name)
+    numberoflines = len(edit_block)
+    print("- Number of sites in supercell: ", numberoflines)
+    print("- Element and occupancy: ", atomoccpairslist) # The number of elements in this site = N
+    proportions = [t[1] for t in atomoccpairslist]
+    combinations = enumerate_site(numberoflines, proportions)[1]
+
+    return combinations
+
+
+def enumerate_structure(input_file):
+    # Given a SUPERCELL .cif structure, return total possible virtual cells,
+    # disregarding symmetry equivalence
+    print("Input supercell .cif file: ", input_file)
+
+    # Updated regex pattern to capture the second string and the last number
+    pattern = re.compile(r'\s*\S+\s+(\S+)\s+1\s+[0-9]+\.[0-9]+\s+[0-9]+\.[0-9]+\s+[0-9]+\.[0-9]+\s+([0-9]+\.[0-9]+)')
+    product_list = [] # list of permutations to include in
+
+    # Open the input file to read and the output file to write
+    with open(input_file, 'r') as infile:
+        # Declare edit space (as in permutative fill, but without updating)
+        edit_active = False # is thisline in an editing block?
+        edit_block = []     # array to store lines in an editing block
+        edit_name = ""      # stores the site which forms the edit block
+        
+        for thisline in infile: # scan through the file
+            # Check if the line matches the pattern
+            match = pattern.match(thisline)
+            
+            if match: # we have reached the coordinate block of the .cif file
+                # Extract the site name and last number from the match
+                second_string = match.group(1)  # This will give you 'Ca1'
+                last_number = float(match.group(2)) # The last number
+    
+                # Decision block
+                if last_number < 1.0: # Check if the last number is less than 1.0: partial occupancy site
+                    if not edit_active: # if first line in an edit block
+                        edit_active = True # switch on editing mode
+                        edit_name = second_string # What site is being edited
+                    else:
+                        if not edit_name == second_string: # if a different site is being considered
+                            product_list.append(get_site_combination(edit_block, edit_name)) # get combinations for site
+                            # Re-initialize edit parameters
+                            edit_block = []     # array to store lines in an editing block
+                            edit_active = True
+                            edit_name = second_string
+                            
+                else: # if no longer partial occupancy site
+                    if edit_active: 
+                        product_list.append(get_site_combination(edit_block, edit_name)) # get combinations for site
+                        # Re-initialize edit parameters
+                        edit_active = False # switch off edit mode
+                        edit_block = []     # array to store lines in an editing block
+                        edit_name = ""      # stores the site which forms the edit block
+
+                if edit_active:
+                    # Write the line to the edit block
+                    edit_block.append(thisline)
+    
+    totalcombinations = prod(product_list)
+    print("Total number of combinations for", input_file, ": ", format_integer(totalcombinations))
+    return totalcombinations

virp-1.0.0/virp/main.py

@@ -0,0 +1,320 @@
+# main.py
+
+# External Imports
+from pymatgen.core.structure import Structure
+from chgnet.model import StructOptimizer
+from itertools import product
+import numpy as np
+import pandas as pd
+import warnings
+import random
+import math
+import re
+import os
+
+
+def CIFSupercell (inputcif, outputcif, supercellsize):
+    # inputcif, outputcif: path to cif file
+    # supercellsize: vector of 3 integers
+
+    # Load the structure from a CIF file
+    structure = Structure.from_file(inputcif)
+
+    # Define the scaling matrix for the supercell
+    # For example, [2, 0, 0], [0, 2, 0], [0, 0, 2] creates a 2x2x2 supercell
+    scaling_matrix = [[supercellsize[0], 0, 0], 
+                      [0, supercellsize[1], 0], 
+                      [0, 0, supercellsize[2]]]
+
+    # Create the supercell
+    structure.make_supercell(scaling_matrix)
+
+    # Save the supercell to a new CIF file (optional)
+    structure.to(fmt="cif", filename=outputcif)
+    print("Supercell created and saved as ", outputcif)
+
+
+def round_with_tie_breaker(n):
+    # Separate the fractional and integer parts
+    fractional_part, integer_part = math.modf(n)
+    
+    # Check if the fractional part is 0.5
+    if abs(fractional_part) == 0.5:
+        # Randomly choose to round down or up
+        return int(integer_part) + random.choice([0, 1])
+    else:
+        # Regular rounding for non 0.5 cases
+        return round(n)
+    
+
+def ShuffleOccupiedSites (outfile, edit_block, edit_name):
+    # Auxiliary function which, outside of the permutative fill routine, will make no sense whatsoever
+
+    # 1. What are the unique elements and occupancies?
+    atomoccpairslist = []
+    for evalline in edit_block:
+        # Split each line into components (using split will automatically handle whitespaces)
+        parts = evalline.split()
+        atomoccpair = (parts[0], float(parts[-1]))
+        if atomoccpair not in atomoccpairslist:
+            atomoccpairslist.append(atomoccpair)
+
+    # Display specifications
+    print("Disordered site name: ", edit_name)
+    numberofelements = len(atomoccpairslist)
+    print("- Number of elements in this site: ", numberofelements) # The number of elements in this site = N
+
+    # Keep every Nth line in the edit block
+    if numberofelements > 1: edit_block = edit_block[::numberofelements]
+
+    # Randomly shuffle the list
+    random.shuffle(edit_block)
+
+    # Assign atoms based on proportion in atomoccpairslist
+    numberoflines = len(edit_block)
+    print("- Number of sites in supercell: ", numberoflines)
+
+    atomassignmentlist_float = []
+    assignment_cumulative = 0
+    assignment_cumulative_int = 0
+    for atomoccpair in atomoccpairslist:
+        # evaluate how many atoms to assign to element in question
+        atomassignment_float = atomoccpair[1]*numberoflines
+        assignment_cumulative += atomassignment_float
+        assignment_int = max(round_with_tie_breaker(assignment_cumulative)-assignment_cumulative_int,1) # assign at least 1 atom
+        assignment_cumulative_int += assignment_int
+        # tuples for display
+        atomassignmentlist_float.append((atomoccpair[0], atomassignment_float, assignment_int))
+        
+    print("- Atoms and site assignment (float/rounded): ", atomassignmentlist_float)
+    print("- No of filled sites: ", assignment_cumulative_int,"/",len(edit_block))
+    edit_block = edit_block[:assignment_cumulative_int]
+
+    # Implement the atom-site assignment in-text
+    pointer = 0 # line-by line pointer for edit_block rows
+    for this_element in atomassignmentlist_float:
+        element_name = this_element[0]
+        no_atoms = this_element[2]
+        for i in range(no_atoms):
+            edit_block[pointer] = re.sub(r'^(\s*)([^\s]+)', r'\1' + element_name, edit_block[pointer])
+            pointer += 1
+
+    # Change every occupancy to 1.0
+    edit_block = [re.sub(r'([0-9]+\.[0-9]+)\s*$', '1.0', line) + '\n' for line in edit_block]
+    
+    for writeline in edit_block: outfile.write(writeline)
+
+
+def PermutativeFill(input_file, output_file):
+    # Updated regex pattern to capture the second string and the last number
+    pattern = re.compile(r'\s*\S+\s+(\S+)\s+1\s+[0-9]+\.[0-9]+\s+[0-9]+\.[0-9]+\s+[0-9]+\.[0-9]+\s+([0-9]+\.[0-9]+)')
+    
+    # Open the input file to read and the output file to write
+    with open(input_file, 'r') as infile, open(output_file, 'w') as outfile:
+        # Declare edit space (a series of lines where permutative fill takes place)
+        edit_active = False # is thisline in an editing block?
+        edit_block = []     # array to store lines in an editing block
+        edit_name = ""      # stores the site which forms the edit block
+        
+        for thisline in infile: # scan through the file
+            # Check if the line matches the pattern
+            match = pattern.match(thisline)
+            
+            if match: # we have reached the coordinate block of the .cif file
+                # Extract the site name and last number from the match
+                second_string = match.group(1)  # This will give you 'Ca1'
+                last_number = float(match.group(2)) # The last number
+    
+                # Decision block
+                
+                if last_number < 1.0: # Check if the last number is less than 1.0: partial occupancy site
+                    if not edit_active: # if first line in an edit block
+                        edit_active = True # switch on editing mode
+                        edit_name = second_string # What site is being edited
+                    else:
+                        if not edit_name == second_string: # if a different site is being considered
+                            ShuffleOccupiedSites(outfile, edit_block, edit_name) # WRITE EDITING BLOCK TO FILE; this also resets it to []
+                            # Re-initialize edit parameters
+                            edit_block = []     # array to store lines in an editing block
+                            edit_active = True
+                            edit_name = second_string
+                            
+                else: # if no longer partial occupancy site
+                    if edit_active: 
+                        ShuffleOccupiedSites(outfile, edit_block, edit_name) # WRITE EDITING BLOCK TO FILE
+                        # Re-initialize edit parameters
+                        edit_active = False # switch off edit mode
+                        edit_block = []     # array to store lines in an editing block
+                        edit_name = ""      # stores the site which forms the edit block
+
+                # Execution block
+    
+                if edit_active:
+                    # Write the line to the edit block
+                    edit_block.append(thisline)
+    
+                else: # edit mode is not active
+                    # Write the thisline to the output file
+                    outfile.write(thisline)
+    
+            else: # other lines we are not bothered with
+                outfile.write(thisline)
+                if edit_active: # we have reached the end of the coordinate block
+                    edit_active = False # switch off edit mode
+                    
+                    # WRITE SEQUENCE
+                    ShuffleOccupiedSites(outfile, edit_block, edit_name)
+                    # Re-initialize edit parameters
+                    edit_block = []     # array to store lines in an editing block
+                    edit_name = ""      # stores the site which forms the edit block
+
+
+def SampleVirtualCells(input_cif, supercell, sample_size=400):
+    """
+    Given a disordered .cif file, create an output folder
+    containing a number (sample_size) of virtual cells
+    
+    Args:
+        input_cif (str): Path to .cif (disordered)
+        supercell [int,int,int]: multiplicity of supercell
+        sample_size (int): Number of virtual cells to generate (default is 400)
+        
+    Returns:
+        void
+    """
+    # Init CHGNET optimizer
+    relaxer = StructOptimizer()
+
+    # Suppress warnings in this block
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+
+        # Make output folder directory
+        fname = os.path.splitext(os.path.basename(input_cif))[0]
+        os.makedirs(fname, exist_ok=True)  # `exist_ok=True` avoids errors if the directory exists.
+        print(f"Directory created at: {fname}")
+
+        header = os.path.join(fname,fname)
+        sc_file = header+"_supercell.cif"
+
+        # Make the supercell
+        CIFSupercell (input_cif, sc_file, supercell)
+
+        # Create target folders if they don't exist
+        stropt_path = os.path.join(fname,"stropt")
+        no_stropt_path = os.path.join(fname,"no_stropt")
+        os.makedirs(stropt_path, exist_ok=True) # structure-optimized cells
+        os.makedirs(no_stropt_path, exist_ok=True) # non-structure-optimized cells
+
+        # Execution
+        for i in range(sample_size):
+            # Permutative fill only, no structure optimization
+            print("Generating virtual cell #", i, ":")
+            pfill_file_name = fname+"_virtual_"+str(i)+".cif"
+            pfill_file = os.path.join(no_stropt_path,pfill_file_name)
+            PermutativeFill(sc_file, pfill_file)
+
+            # Relax
+            structure = Structure.from_file(pfill_file)
+            result = relaxer.relax(structure, verbose=False)
+            stropt_file_name = fname+"_virtual_"+str(i)+"_stropt.cif"
+            stropt_file = os.path.join(stropt_path,stropt_file_name)
+            result['final_structure'].to(stropt_file)
+        
+        with open(os.path.join(fname,"_JOBDONE"), 'w') as file: pass # make an empty file signalling completion
+        print("All cells generated (see _JOBDONE file).")
+
+
+def SupercellSize(input_cif, minsize=15.0):
+    """
+    Given a disordered .cif file, decide how big the
+    supercell should be (works best for orthogonal cifs)
+    
+    Args:
+        input_cif (str): Path to .cif (disordered)
+        minsize (float): minimum tolerated distance between
+            lattice points in one direction
+
+    Returns:
+        array of 3 integers denoting supercell multiplicity
+    """
+    # init sc_size array, warning
+    sc_size = [0,0,0]
+    warning = False
+
+    # Load the .cif file
+    structure = Structure.from_file(input_cif)
+
+    # Get the lattice vectors
+    lattice = structure.lattice
+    new_lattice = []
+
+    # Execution
+    for i in range(3):
+        uc_length = np.linalg.norm(lattice.matrix[i])
+        sc_size[i] = math.ceil(minsize/uc_length)
+        new_lattice.append(lattice.matrix[i]*sc_size[i])
+
+    # Generate all lattice points for one unit cell
+    lattice_points = [np.dot([i, j, k], new_lattice) for i, j, k in product([0, 1], repeat=3)]
+    # Calculate all pairwise distances
+    distances = []
+    for i, p1 in enumerate(lattice_points):
+        for j, p2 in enumerate(lattice_points):
+            if i < j:  # Avoid duplicate pairs
+                distances.append(np.linalg.norm(p1 - p2))
+
+    # Find the shortest distance
+    shortest_lattice_distance = min(distances)
+
+    # Check if shortest distance between lattice points is under minsize
+    print(f"The shortest distance between lattice points is: {shortest_lattice_distance:.5f} Å")
+    if shortest_lattice_distance < minsize:
+        print("Warning: lattice points still close together for supercell; check orthogonality!")
+        warning = True
+    print(f"Supercell multiplicity: {sc_size}")
+
+    return sc_size, warning
+
+
+def Session(folder_path = "_disordered_cifs", mindist = 15, no_of_samples = 400):
+    # init DataFrame to store results
+    data = []
+
+    # Loop through all .cif files in the folder
+    for filename in os.listdir(folder_path):
+        if filename.endswith(".cif"):  # Check if the file has a .cif extension
+            file_path = os.path.join(folder_path, filename)
+            print(f"Processing .cif file: {file_path}")
+
+            try:
+                # Calculate preferred supercell size
+                sc_size, warning = SupercellSize(file_path, minsize=mindist)
+
+                # Generate virtual cell samples
+                SampleVirtualCells(file_path, sc_size, sample_size=no_of_samples)
+
+                # Extract metadata: chemical formula
+                structure = Structure.from_file(file_path)
+                formula = structure.composition.reduced_formula
+
+                # Append results to the data list
+                data.append({
+                    "filename": filename,
+                    "folder": folder_path,
+                    "formula": formula,
+                    "supercell size": sc_size,
+                    "sample size": no_of_samples,
+                    "lattice spacing warning": warning
+                })
+
+            except Exception as e:
+                print(f"Error processing {file_path}: {e}")
+
+    # Create a DataFrame
+    df = pd.DataFrame(data)
+
+    # Save the DataFrame to a CSV file
+    output_file = "virp_session_summary.csv"
+    df.to_csv(output_file)
+    print(f"Results saved to {output_file}")

virp-1.0.0/virp/matprop.py

@@ -0,0 +1,120 @@
+# matprop.py
+
+from pymatgen.core.structure import Structure
+import os
+import csv
+import torch
+import matgl
+from chgnet.model.model import CHGNet
+
+def VirtualCellProperties(folder_path, output_csv):
+    # To add: customise the set of properties to evaluate
+    """
+    Given a folder filled with virtual cells, 
+    predict material properties for each virtual cell,
+    and write results in a .csv form
+    
+    Args:
+        folder_path (str): Path to folder
+        output_csv (str): Path to .csv output
+        
+    Returns:
+        void
+    """
+    # Load the MEGNet band gap model
+    bandgap_model = matgl.load_model("MEGNet-MP-2019.4.1-BandGap-mfi")
+    
+    # Load the CHGNet model for total energy prediction
+    chgnet = CHGNet.load()
+
+    # Initialize data storage
+    data = []
+
+    for filename in os.listdir(folder_path):
+        if filename.endswith("stropt.cif"): # evaluate structure-optimized cells only
+            filepath = os.path.join(folder_path, filename)
+            try:
+                # Load the structure
+                structure = Structure.from_file(filepath)
+                
+                # Predict total energy
+                total_energy = chgnet.predict_structure(structure)['e']
+
+                # Calculate density and convert to float
+                density = float(structure.density)
+
+                # Predict band gaps for different methods
+                bandgaps = {}
+                for i, method in ((0, "PBE"), (1, "GLLB-SC"), (2, "HSE"), (3, "SCAN")):
+                    graph_attrs = torch.tensor([i])
+                    bandgap = bandgap_model.predict_structure(structure=structure, state_attr=graph_attrs)
+                    bandgaps[method] = float(bandgap)
+                
+                # Append results to data
+                data.append({
+                    "File": filename,
+                    "Total Energy (eV)": total_energy,
+                    "Density": density,
+                    "PBE Bandgap (eV)": bandgaps["PBE"],
+                    "GLLB-SC Bandgap (eV)": bandgaps["GLLB-SC"],
+                    "HSE Bandgap (eV)": bandgaps["HSE"],
+                    "SCAN Bandgap (eV)": bandgaps["SCAN"],
+                })
+                
+                print(f"Processed: {filename}")
+            
+            except Exception as e:
+                print(f"Error processing {filename}: {e}")
+    
+    # Write results to CSV
+    with open(output_csv, mode='w', newline='') as csvfile:
+        fieldnames = ["File", "Total Energy (eV)", "Density", "PBE Bandgap (eV)", "GLLB-SC Bandgap (eV)", "HSE Bandgap (eV)", "SCAN Bandgap (eV)"]
+        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
+        
+        writer.writeheader()
+        writer.writerows(data)
+
+    print(f"Results saved to {output_csv}")
+
+
+import pandas as pd
+import numpy as np
+
+def ExpectationValues(csv_path, temperature):
+    """
+    Calculate Boltzmann-weighted expectation values for all numeric properties
+    
+    Args:
+        csv_path (str): Path to CSV file
+        temperature (float): Temperature in Kelvin
+        
+    Returns:
+        tuple: (DataFrame, dictionary of expectation values)
+    """
+    # Read the CSV file
+    df = pd.read_csv(csv_path)
+    
+    # Boltzmann constant in eV/K = 0.00008617
+    k_B = 0.0000861733326
+    
+    # Calculate weights using the Boltzmann distribution formula
+    df['weights'] = np.exp(-df['Total Energy (eV)']/(k_B * temperature))
+    
+    # Calculate total weights
+    total_weights = df['weights'].sum()
+    
+    # Dictionary to store expectation values
+    expectation_values = {}
+    
+    # Get all numeric columns except 'Total Energy (eV)' and 'weights'
+    excluded_cols = ['File', 'Total Energy (eV)', 'weights']
+    numeric_cols = df.select_dtypes(include=[np.number]).columns
+    properties = [col for col in numeric_cols if col not in excluded_cols]
+    
+    # Calculate weighted properties and their expectation values
+    for prop in properties:
+        weighted_col_name = f'weighted_{prop}'
+        df[weighted_col_name] = (df[prop] * df['weights']) / total_weights
+        expectation_values[prop] = df[weighted_col_name].sum()
+    
+    return df, expectation_values

virp-1.0.0/virp.egg-info/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.2
+Name: virp
+Version: 1.0.0
+Summary: VIRtual cell generation by Permutation
+Author-email: Andy Paul Chen <la.vache.qui.vit@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Kedar Hippalgaonkar's Materials by Design Lab
+        
+        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.
+        
+Keywords: disordered,virtual cell,cif,partial occupancy
+Classifier: Programming Language :: Python :: 3.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymatgen
+Requires-Dist: chgnet
+Requires-Dist: matgl==1.0.0
+Requires-Dist: dgl==1.1.2
+Requires-Dist: poshcar
+
+<img src="graphics/virpbanner.png" width="870">
+
+# `virp`: VIRtual cell generation by Permutation
+ `virp` is a code for the fast generation of a virtual cell from a crystal structure (in CIF format) containing site disorder. It is named after Singapore's first superhero, VR Man, whose superpower is "Virping". The show was a flop, but we are still proud of him. 
+ 
+ This project is inspired by the `Supercell` code of Okhotnikov, Charpentier and Cadars (<i>J. Cheminform. <b>8</b>, 17</i>), which formed the basis of our fast virtual cell generation algorithm, as well as the `aflow++` framework (<i>Comput. Mater. Sci. <b>217</b>, 111889</i>), for the statistical postprocessing of materials properties.
+
+ ## Theory
+ (To be updated!)
+
+ ## Requirements
+`pymatgen`, `chgnet`, and `matgl` (`matgl==1.0.0`; `dgl==1.1.2`)<br>
+ __Optional__: You can also use git for the fancy installation. Otherwise, downloading the .py file will do.
+
+ ## Installation
+ `pip install git+https://github.com/andypaulchen/virp.git`<br>
+ Update to latest release: uninstall and re-install
+
+ ## Building a database
+ The root directory has a folder (`session`) which holds the python scripts which build a library of virtual cells (`generate.py`) and postprocessing scripts (`connectivity.py` and `properties.py`). After each script is run, the results are saved as `.csv` files.
+
+ 1. To prepare for a session, copy the `session` folder in your workspace and place the `.cif` files you want to process (make virtual cells + postprocessing) in the subfolder `_disordered_cifs`. Feel free to rename `session` folder to something more identifiable
+
+ 2. Run `generate.py` to create a supercell and (by default) 400 virtual cells.
+    - after this step, a structure subfolder (e.g. `structure`) is created in `session` for each `structure.cif` file in `_disordered_cifs`, with the same name. Inside this folder is a supercell CIF and folders for structure-optimized (`stropt`) and non-structure-optimized virtual cells (`no_stropt`). The details of this run is recorded in `virp_session_summary.csv`.
+
+ 3. Run `connectivity.py` for atomic connectivity post-processing
+    - after this step, the results are written to `connectivity.csv` and `scatterplot.png` under `stropt` and `no_stropt`.
+
+ 4. Run `properties.py` to predict materials properties. This is performed on `stropt` subfolders only.
+    - after this step, the results are written to `virtual_properties.csv` in the `structure` subfolder.
+
+ In summary, this is what a session looks like after all three routines have completed:
+
+ <img src="graphics/operation.png" width="870">
+
+ ## Versions and changelog
+ `v0.1.1`: first workable code, with function to generate a virtual cell. <br>
+ `v0.2.1`: added enumeration function <br>
+ `v0.2.2`: enumeration can be imported now (fix) <br>
+ `v0.3.0`: you can now make a batch of virtual cells<br>
+ `v0.4.3`: added tools to build a database
+
+ ## Debugging and support
+ The `virp` code has been tested on a limited number of platforms, so far Windows and Linux. If you are running into any problems during operation, please hound me (Andy Paul Chen) at la.vache.qui.vit(at)gmail.com, and I will try my best to help.
+ 

virp-1.0.0/virp.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+virp/__init__.py
+virp/database.py
+virp/enumerate.py
+virp/main.py
+virp/matprop.py
+virp.egg-info/PKG-INFO
+virp.egg-info/SOURCES.txt
+virp.egg-info/dependency_links.txt
+virp.egg-info/requires.txt
+virp.egg-info/top_level.txt

virp-1.0.0/virp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

virp-1.0.0/virp.egg-info/requires.txt

@@ -0,0 +1,5 @@
+pymatgen
+chgnet
+matgl==1.0.0
+dgl==1.1.2
+poshcar

virp-1.0.0/virp.egg-info/top_level.txt

@@ -0,0 +1 @@
+virp