ion-CSP 2.1.5__py3-none-any.whl → 2.1.8__py3-none-any.whl

ion_CSP/log_and_time.py

@@ -11,7 +11,14 @@ from dpdispatcher.dlog import dlog
 
 
 def log_and_time(func):
-    """Decorator for recording log information and script runtime"""
+    """
+    Decorator for recording log information and script runtime
+
+    :params
+        func: The function to be decorated
+        
+    :return: The decorated function with logging and timing capabilities
+    """
     @functools.wraps(func)
     def wrapper(work_dir, *args, **kwargs):
         # 使用inspect获取真实脚本文件名
@@ -54,20 +61,49 @@ def log_and_time(func):
 
 
 def merge_config(default_config, user_config, key):
+    """
+    Merge default configuration with user-provided configuration for a specific key.
+
+    :params 
+        default_config: The default configuration dictionary.
+        user_config: The user-provided configuration dictionary.
+        key: The key for which the configuration should be merged.
+
+    :return: A merged configuration dictionary for the specified key.
+    """
+    if key not in default_config:
+        raise KeyError(f"Key '{key}' not found in default configuration.")
+    if key not in user_config:
+        raise KeyError(f"Key '{key}' not found in user configuration.")
+    if not isinstance(default_config[key], dict) or not isinstance(user_config.get(key, {}), dict):
+        raise TypeError(f"Both default and user configurations for '{key}' must be dictionaries.")
+    # 合并两个参数配置，优先使用用户参数配置
     return {**default_config[key], **user_config.get(key, {})}
 
 
 class StatusLogger:
+    """
+    A singleton class to log the status of a workflow, including RUNNING, SUCCESS, FAILURE, and KILLED.
+    It initializes a logger that writes to a log file and a YAML file to record the status of the workflow.
+    The logger captures the process ID and handles termination signals (SIGINT, SIGTERM).
+    """
+    _name = "WorkflowLogger"
     _instance = None
 
     def __new__(cls, *args, **kwargs):
+        """Ensure that only one instance of StatusLogger is created (Singleton Pattern)"""
         if not cls._instance:
             cls._instance = super(StatusLogger, cls).__new__(cls)
             cls._instance.__init__(*args, **kwargs)
         return cls._instance
 
     def __init__(self, work_dir, task_name):
-        """Initialize workflow status logger and generate the .log and .yaml file to record the status"""
+        """
+        Initialize workflow status logger and generate the .log and .yaml file to record the status
+
+        :params
+            work_dir: The working directory where the log and yaml files will be created
+            task_name: The name of the task to be logged"""
         # 使用单例模式，避免重复的日志记录，缺点是再重新给定task_name之后会覆盖原来的实例，只能顺序调用
         self.task_name = task_name
         log_file = os.path.join(work_dir, "workflow_status.log")
@@ -97,12 +133,17 @@ class StatusLogger:
         self._init_yaml()
 
     def set_running(self):
+        """
+        Set the current task status to RUNNING and log the event.
+        This method increments the run count and updates the YAML file.
+        """
         self.current_status = "RUNNING"
         self.logger.info(f"{self.task_name} Status: {self.current_status}")
         self.run_count += 1
         self._update_yaml()
 
     def set_success(self):
+        """Set the current task status to SUCCESS and log the event"""
         self.current_status = "SUCCESS"
         self.logger.info(f"{self.task_name} Status: {self.current_status}\n")
         self._update_yaml()
@@ -112,12 +153,16 @@ class StatusLogger:
         return self.current_status == "SUCCESS"
 
     def set_failure(self):
+        """Set the current task status to FAILURE and log the event"""
         self.current_status = "FAILURE"
         self.logger.error(f"{self.task_name} Status: {self.current_status}\n")
         self._update_yaml()
 
     def _signal_handler(self, signum, _):
-        """Handle termination signals and log the event"""
+        """
+        Handle termination signals and log the event
+        :params
+            signum: The signal number received (e.g., SIGINT, SIGTERM)"""
         if signum == 2:
             self.logger.warning(
                 f"Process {os.getpid()} has been interrupted by 'Ctrl + C'\n"
@@ -134,6 +179,7 @@ class StatusLogger:
         sys.exit(0)
 
     def _set_killed(self):
+        """Set the current task status to KILLED and log the event"""
         self.current_status = "KILLED"
         self.logger.warning(f"{self.task_name} Status: {self.current_status}\n")
         self._update_yaml()
@@ -193,11 +239,12 @@ def redirect_dpdisp_logging(custom_log_path):
 
 
 def get_work_dir_and_config():
-    """获取工作目录并加载配置文件
-    Returns:
-        tuple: (工作目录路径, 合并后的配置字典)
-    Raises:
-        SystemExit: 当输入无效时退出程序
+    """
+    Get the working directory and user configuration from command line arguments or interactive input.
+    If the working directory is not specified, it prompts the user to input it interactively.
+    It also reads the configuration from a 'config.yaml' file in the specified directory.
+    
+    :return: A tuple containing the working directory and the user configuration dictionary.
     """
     parser = argparse.ArgumentParser(
         description="The full workflow of ionic crystal design for a certain ion combination, including generation, mlp optimization, screening, vasp optimization and analysis."

ion_CSP/mlp_opt.py

@@ -14,13 +14,22 @@ base_dir = os.path.dirname(__file__)
 relative_path = './model.pt'
 file_path = os.path.join(base_dir, relative_path)
 calc = DP(file_path)
-'''
+"""
 structure optimization with DP model and ASE
 PSTRESS and fmax should exist in input.dat
-'''
+"""
 
 def get_element_num(elements):
-    '''Using the Atoms.symples to Know Element&Num'''
+    """
+    Using the Atoms.symples to Know Element and Number
+
+    :params
+        elements: list of elements in the structure
+
+    :returns
+        element: list of unique elements in the structure
+        ele: dictionary with elements as keys and their counts as values
+    """
     element = []
     ele = {}
     element.append(elements[0])
@@ -32,7 +41,15 @@ def get_element_num(elements):
     return element, ele 
         
 def write_CONTCAR(element, ele, lat, pos, index):
-    '''Write CONTCAR''' 
+    """
+    Write CONTCAR file in VASP format
+
+    :params
+        element: list of elements in the structure
+        ele: dictionary of element counts
+        lat: lattice vectors
+        pos: atomic positions in direct coordinates
+        index: index for the output file""" 
     f = open(f'{base_dir}/CONTCAR_'+str(index),'w')
     f.write('ASE-DPKit-Optimization\n')
     f.write('1.0\n') 
@@ -51,7 +68,21 @@ def write_CONTCAR(element, ele, lat, pos, index):
         f.write('%15.10f %15.10f %15.10f\n' % tuple(dpos[i]))
         
 def write_OUTCAR(element, ele, masses, volume, lat, pos, ene, force, stress, pstress, index):
-    '''Write OUTCAR'''
+    """
+    Write OUTCAR file in VASP format
+    :params
+        element: list of elements in the structure
+        ele: dictionary of element counts
+        masses: total mass of the atoms
+        volume: volume of the unit cell
+        lat: lattice vectors
+        pos: atomic positions in direct coordinates
+        ene: total energy of the system
+        force: forces on the atoms
+        stress: stress tensor components
+        pstress: external pressure
+        index: index for the output file
+    """
     f = open(f'{base_dir}/OUTCAR_'+str(index),'w')
     for x in element: 
         f.write('VRHFIN =' + str(x) + '\n')
@@ -88,6 +119,13 @@ def write_OUTCAR(element, ele, masses, volume, lat, pos, ene, force, stress, pst
     f.write('enthalpy TOTEN    = %20.6f %20.6f\n' % (enthalpy, enthalpy/na)) 
         
 def get_indexes():
+    """
+    Get the indexes of POSCAR files in the current directory.
+    This function scans the current directory for files starting with 'POSCAR_' and extracts their numeric indexes.
+
+    :returns
+        A sorted list of indexes extracted from the POSCAR files.
+    """
     base_dir = os.path.dirname(__file__)
     POSCAR_files = [f for f in os.listdir(base_dir) if f.startswith('POSCAR_')]
     indexes = []
@@ -100,7 +138,11 @@ def get_indexes():
     return indexes
 
 def run_opt(index: int): 
-    '''Using the ASE&DP to Optimize Configures''' 
+    """
+    Using the ASE&DP to Optimize Configures
+    :params
+        index: index of the POSCAR file to be optimized
+    """
     if os.path.isfile(f'{base_dir}/OUTCAR'):
         os.system(f'mv {base_dir}/OUTCAR {base_dir}/OUTCAR-last')
     fmax, pstress = 0.03, 0
@@ -143,6 +185,10 @@ def run_opt(index: int):
 
 
 def main():
+    """
+    Main function to run the optimization in parallel.
+    It initializes a multiprocessing pool and maps the run_opt function to the indexes of POSCAR files.
+    """
     ctx=multiprocessing.get_context("spawn")
     pool=ctx.Pool(8)
     indexes = get_indexes()

ion_CSP/read_mlp_density.py

@@ -9,6 +9,13 @@ from ion_CSP.identify_molecules import identify_molecules, molecules_information
 class ReadMlpDensity:
     
     def __init__(self, work_dir:str):
+        """
+        This class is designed to read and process MLP optimized files, specifically CONTCAR files, to calculate and sort their densities.
+        The class also provides functionality to process these files using phonopy for symmetry analysis and primitive cell generation.
+
+        :params
+            work_dir: The working directory where the MLP optimized files are located.
+        """
         # 获取脚本的当前目录
         self.base_dir = work_dir
         os.chdir(self.base_dir)
@@ -39,7 +46,10 @@ class ReadMlpDensity:
         """
         Obtain the atomic mass and unit cell volume from the optimized CONTCAR file, and obtain the ion crystal density. Finally, take n CONTCAR files with the highest density and save them separately for viewing.
         
-        :param n_screen: 取前n个最大密度的文件
+        :params
+            n_screen: The number of CONTCAR files with the highest density to be saved.
+            molecules_screen: If True, only consider ionic crystals with original ions.
+            detail_log: If True, print detailed information about the molecules identified in the CONTCAR files.
         """
         os.chdir(self.base_dir)
         # 获取所有以'CONTCAR_'开头的文件，并按数字顺序处理
@@ -135,6 +145,10 @@ class ReadMlpDensity:
     def phonopy_processing_max_density(self, specific_directory :str = None):
         """
         Use phonopy to check and generate symmetric primitive cells, reducing the complexity of subsequent optimization calculations, and preventing pyxtal.from_random from generating double proportioned supercells. 
+        
+        :params
+            specific_directory: If specified, phonopy will process the files in this directory instead of the max_density directory.
+            If not specified, it will process the files in the max_density directory.
         """
         if specific_directory:
             self.phonopy_dir = os.path.join(self.base_dir, specific_directory)

ion_CSP/task_manager.py

@@ -225,7 +225,7 @@ class TaskManager:
         pid_file = work_dir / "pid.txt"
 
         # 动态加载模块
-        module_name = f"run.main_{module}"
+        module_name = f"ion_CSP.run.main_{module}"
         spec = importlib.util.find_spec(module_name)
         if not spec:
             raise ImportError(f"Module {module_name} not found")

ion_CSP/upload_download.py

@@ -484,4 +484,3 @@ class SSHBatchJob:
     def close_connection(self):
         self.sftp.close()
         self.client.close()
-

ion_CSP/vasp_processing.py

@@ -4,6 +4,7 @@ import json
 import yaml
 import shutil
 import logging
+import importlib.resources
 from ase.io import ParseError
 from ase.io.vasp import read_vasp_out
 from dpdispatcher import Machine, Resources, Task, Submission
@@ -13,12 +14,18 @@ from ion_CSP.identify_molecules import identify_molecules, molecules_information
 
 class VaspProcessing:
     def __init__(self, work_dir: str):
+        """
+        This directory is used to store all the files related to VASP optimizations.
+
+        :params
+            work_dir: The working directory where VASP optimization files will be stored.
+        """
         redirect_dpdisp_logging(os.path.join(work_dir, "dpdispatcher.log"))
         self.base_dir = work_dir
         os.chdir(self.base_dir)
         self.for_vasp_opt_dir = f"{work_dir}/3_for_vasp_opt"
         self.vasp_optimized_dir = f"{work_dir}/4_vasp_optimized"
-        self.param_dir = os.path.join(os.path.dirname(__file__), "../../param")
+        self.param_dir = importlib.resources.files("ion_CSP.param")
 
     def dpdisp_vasp_optimization_tasks(
         self,
@@ -28,6 +35,10 @@ class VaspProcessing:
     ):
         """
         Based on the dpdispatcher module, prepare and submit files for optimization on remote server or local machine.
+        :params
+            machine: The machine configuration file, which can be in JSON or YAML format.
+            resources: The resources configuration file, which can be in JSON or YAML format.
+            nodes: The number of nodes to distribute the optimization tasks across.
         """
         # 调整工作目录，减少错误发生
         os.chdir(self.for_vasp_opt_dir)
@@ -79,7 +90,7 @@ class VaspProcessing:
             task_dir = os.path.join(self.for_vasp_opt_dir, f"{parent}pop{pop}")
             os.makedirs(task_dir, exist_ok=True)
             for file in forward_files:
-                shutil.copyfile(f"{self.param_dir}/{file}", f"{task_dir}/{file}")
+                shutil.copyfile(self.param_dir.joinpath(file), f"{task_dir}/{file}")
             for job_i in node_jobs[pop]:
                 # 将分配好的POSCAR文件添加到对应的上传文件中
                 forward_files.append(mlp_contcar_files[job_i])
@@ -146,7 +157,11 @@ class VaspProcessing:
         nodes: int = 1,
     ):
         """
-        Based on the dpdispatcher module, prepare and submit files for optimization on remote server or local machine.
+        Based on the dpdispatcher module, prepare and submit files for VASP relaxation on remote server or local machine.
+        :params
+            machine: The machine configuration file, which can be in JSON or YAML format.
+            resources: The resources configuration file, which can be in JSON or YAML format.
+            nodes: The number of nodes to distribute the optimization tasks across.
         """
         # 调整工作目录，减少错误发生
         os.chdir(self.vasp_optimized_dir)
@@ -199,7 +214,7 @@ class VaspProcessing:
             task_dir = os.path.join(self.vasp_optimized_dir, f"{parent}pop{pop}")
             os.makedirs(task_dir, exist_ok=True)
             for file in forward_files:
-                shutil.copyfile(f"{self.param_dir}/{file}", f"{task_dir}/{file}")
+                shutil.copyfile(self.param_dir.joinpath(file), f"{task_dir}/{file}")
             for job_i in node_jobs[pop]:
                 # 将分配好的POSCAR文件添加到对应的上传文件中
                 vasp_dir = vasp_optimized_folders[job_i]
@@ -311,7 +326,7 @@ class VaspProcessing:
             task_dir = os.path.join(self.for_vasp_opt_dir, f"{parent}pop{pop}")
             os.makedirs(task_dir, exist_ok=True)
             for file in forward_files:
-                shutil.copyfile(f"{self.param_dir}/{file}", f"{task_dir}/{file}")
+                shutil.copyfile(self.param_dir.joinpath(file), f"{task_dir}/{file}")
             for job_i in node_jobs[pop]:
                 # 将分配好的POSCAR文件添加到对应的上传文件中
                 forward_files.append(mlp_contcar_files[job_i])
@@ -622,6 +637,11 @@ class VaspProcessing:
             with open(csv_file_path, "r") as csvfile:
                 reader = csv.reader(csvfile)
                 # 跳过表头读取第一行结构序号，即符合结构筛选要求的最大密度结构
+                header = next(reader)
+                if header[0] != "Number":
+                    raise KeyError(
+                        "The first column of the CSV file is not 'Number', please check the file format."
+                    )
                 first_row = next(reader)
                 structure_number = str(first_row[0])
             # 根据结构序号构建要查找的文件夹路径
@@ -632,24 +652,27 @@ class VaspProcessing:
                     structure_number
                 ):
                     # 查找 CONTCAR 文件
-                    final_contcar_path = os.path.join(
-                        vasp_folder_path, "fine", "final", "CONTCAR"
-                    )
+                    # final_contcar_path = os.path.join(
+                    #     vasp_folder_path, "fine", "final", "CONTCAR"
+                    # )
+                    # print(f"Trying to get the final structure from {vasp_folder_path}")
+                    # logging.info(
+                    #     f"Trying to get the final structure from {vasp_folder_path}"
+                    # )
+                    # if os.path.exists(final_contcar_path):
+                    #     # 复制 CONTCAR 文件到 combo_n 文件夹并重命名为 POSCAR
+                    #     shutil.copy(
+                    #         final_contcar_path, os.path.join(self.base_dir, "POSCAR")
+                    #     )
+                    #     print(f"Renamed CONTCAR to POSCAR in {self.base_dir}, copied from {final_contcar_path}")
+                    #     logging.info(
+                    #         f"Renamed CONTCAR to POSCAR in {self.base_dir}, copied from {final_contcar_path}"
+                    #     )
                     fine_contcar_path = os.path.join(
                         vasp_folder_path, "fine", "CONTCAR"
                     )
-                    logging.info(
-                        f"Trying to get the final structure from {vasp_folder_path}"
-                    )
-                    if os.path.exists(final_contcar_path):
-                        # 复制 CONTCAR 文件到 combo_n 文件夹并重命名为 POSCAR
-                        shutil.copy(
-                            final_contcar_path, os.path.join(self.base_dir, "POSCAR")
-                        )
-                        logging.info(
-                            f"Renamed CONTCAR to POSCAR in {self.base_dir}, copied from {final_contcar_path}"
-                        )
-                    elif os.path.exists(fine_contcar_path):
+                    if os.path.exists(fine_contcar_path):
+                        print(f"CONTCAR not found in {os.path.join(vasp_folder_path, 'fine', 'final')}")
                         logging.info(
                             f"CONTCAR not found in {os.path.join(vasp_folder_path, 'fine', 'final')}"
                         )
@@ -657,10 +680,15 @@ class VaspProcessing:
                         shutil.copy(
                             fine_contcar_path, os.path.join(self.base_dir, "POSCAR")
                         )
+                        print(f"Renamed CONTCAR to POSCAR in {self.base_dir}, copied from {fine_contcar_path}")
                         logging.info(
                             f"Renamed CONTCAR to POSCAR in {self.base_dir}, copied from {fine_contcar_path}"
                         )
                     else:
                         print(f"Eligible CONTCAR not found in {vasp_folder_path}")
+                        logging.info(
+                            f"Eligible CONTCAR not found in {vasp_folder_path}"
+                        )
         else:
+            print(f"CSV file not found in {self.base_dir}")
             logging.info(f"CSV file not found in {self.base_dir}")

{ion_csp-2.1.5.dist-info → ion_csp-2.1.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ion_CSP
-Version: 2.1.5
+Version: 2.1.8
 Summary: Crystal Structure Design Software Based on Molecular/Ionic Configuration.
 Home-page: https://github.com/bagabaga007/ion_CSP
 Author: Ze Yang
@@ -28,13 +28,16 @@ Dynamic: home-page
 Dynamic: license-file
 Dynamic: requires-python
 
-# Crystal Structure Design Software V2.1
+# 基于分子/离子构型的晶体结构设计软件 V2.1
 
 ## 项目概述
+
 基于分子/离子构型的晶体结构设计软件通过结合经验公式、机器学习势函数微调、第一性原理分步优化和分子/离子识别技术，实现了从分子/离子构型出发的高效晶体结构设计。该软件采用模块化设计，支持全流程自动化材料筛选，在保证预测精度的同时显著提升计算效率。
 
 ## 功能特性
+
 ### 核心功能
+
 - **双模块工作流**  
   - **EE模块**：基于经验评估的离子组合生成  
   - **CSP模块**：基于离子晶体结构预测的优化筛选  
@@ -48,13 +51,16 @@ Dynamic: requires-python
   - 软链接解析显示实际路径
 
 ### 技术特性
+
 - 跨平台支持（Linux/Docker）
 - 基于Python 3.11+的面向对象架构
 - 集成psutil进程管理
 - 结构化日志记录系统
 
 ## 安装指南
+
 ### 环境要求
+
 | 组件        | 最低版本 |
 |-------------|----------|
 | Python      | 3.11     |
@@ -71,10 +77,13 @@ Dynamic: requires-python
 | rdkit       | 2024.03.3|
 
 ### 安装步骤
+
 ```bash
 pip install ion-csp
 ```
+
 或
+
 ```bash
 # 创建虚拟环境
 python -m venv venv
@@ -87,29 +96,39 @@ pip install -e .
 ```
 
 ## 快速入门
+
 ### 交互模式
+
 ```bash
 ion-csp
 ```
+
 启动交互式命令行界面，支持以下操作：
+
 - 模块选择
 - 日志查看
 - 进程管理
 
 ### 脚本调用
+
 #### EE模块示例
+
 ```bash
 ./scripts/main_EE.sh examples/example_1
 ```
+
 从SMILES表格生成离子组合
 
 #### CSP模块示例
+
 ```bash
 ./scripts/main_CSP.sh examples/example_2
 ```
+
 从离子组合生成并优化晶体结构
 
 ## 技术架构
+
 ```mermaid
 graph TD
     A[用户界面] --> B[任务管理器]
@@ -118,34 +137,32 @@ graph TD
     B --> E[日志系统]
     B --> F[任务调度]
     C --> G[经验评估引擎]
-    D --> H[晶体预测引擎]
+    D --> H[离子晶体结构预测引擎]
     E --> I[结构化日志]
     F --> J[进程终止]
 ```
 
 ## 贡献指南
+
 1. Fork仓库并创建特性分支
 2. 编写单元测试覆盖新功能
 3. 提交Pull Request时注明关联Issue
 4. 遵循PEP8代码规范
 
 ## 许可证
-本项目采用MIT许可证，详见LICENSE文件。
 
-## 技术支持
-- **文档更新**：2025年6月
-- **最新版本**：v2.1.5
-- **问题追踪**：https://github.com/bagabaga007/ion_CSP/issues
+本项目采用MIT许可证，详见LICENSE文件。
 
 ---
 
-# Crystal Structure Design Software V2.1
-
 ## Project Overview
+
 This software enables efficient crystal structure design from molecular/ion configurations by integrating empirical formulas, tuned machine learning potentials, stepwise first-principles optimization, and molecular/ion recognition techniques. The modular architecture ensures extensibility and maintainability while maintaining prediction accuracy.
 
 ## Key Features
+
 ### Core Functionalities
+
 - **Dual-Module Workflow**
   - **EE Module**: Empirical evaluation-based ion combination generation
   - **CSP Module**: Ion crystal structure prediction and optimization
@@ -159,13 +176,16 @@ This software enables efficient crystal structure design from molecular/ion conf
   - Symlink resolution for actual log paths
 
 ### Technical Specifications
+
 - Cross-platform support (Linux/Docker)
 - Object-oriented architecture with Python 3.11+
 - Integrated process management via psutil
 - Structured logging system
 
 ## Installation
+
 ### Prerequisites
+
 | Component   | Min Version |
 |-------------|-------------|
 | Python      | 3.11     |
@@ -182,6 +202,7 @@ This software enables efficient crystal structure design from molecular/ion conf
 | rdkit       | 2024.03.3|
 
 ### Installation Steps
+
 ```bash
 # Create virtual environment
 python -m venv venv
@@ -194,29 +215,39 @@ pip install -e .
 ```
 
 ## Quick Start
+
 ### Interactive Mode
+
 ```bash
 ion-csp
 ```
+
 Launches CLI interface with:
+
 - Module selection
 - Log management
 - Process control
 
 ### Script Execution
+
 #### EE Module Example
+
 ```bash
 ./scripts/main_EE.sh examples/example_1
 ```
+
 Generates ion combinations from SMILES tables
 
 #### CSP Module Example
+
 ```bash
 ./scripts/main_CSP.sh examples/example_2
 ```
+
 Optimizes crystal structures from ion combinations
 
 ## Technical Architecture
+
 ```mermaid
 graph TD
     A[User Interface] --> B[Task Manager]
@@ -225,21 +256,18 @@ graph TD
     B --> E[Log System]
     B --> F[Task Scheduler]
     C --> G[Empirical Evaluation Engine]
-    D --> H[Crystal Prediction Engine]
+    D --> H[Ionic Crystal Structure Prediction Engine]
     E --> I[Structured Logs]
     F --> J[Process Termination]
 ```
 
 ## Contribution Guide
+
 1. Fork repository and create feature branch
 2. Write unit tests for new features
 3. Submit PR with issue reference
 4. Follow PEP8 coding standards
 
 ## License
-MIT License, see LICENSE file.
 
-## Support
-- Documentation last updated: June 2025
-- Latest version: v2.1.5
-- Issue tracker: https://github.com/bagabaga007/ion_CSP/issues
+MIT License, see LICENSE file.