Qn-Util — Qn Network Analysis and RMC Constraint Generation

Qn-Util is a Python library for constructing and analyzing Qn networks from VASP POSCAR/CONTCAR structures and JSON configuration files, and generating constraints for RMC_POT. It outputs Qn distributions, network bond information, and analysis reports.

Main components

• VaspStructure: reads POSCAR files and computes distances and angles under periodic boundary conditions.

• QnNetworkAnalysis: constructs networks from JSON configuration, counts Qn species, and exports network and analysis data.

• RmcConstraintWriter: writes RMC_POT FNC=3 constraints and unit/network topology files.

• QnNetworkBuilder: compatibility facade that exposes analysis and output operations through a single entry point.

• ConfigError: exception used for invalid configuration and input data.

Inputs and outputs

Inputs are a POSCAR/CONTCAR structure and JSON configuration. Outputs include *_qn.csv, *_network_bonds.csv, *_report.txt, *_rmc_fnc3.fnc, and *_rmc_unit.top. Consult the tutorials for configuration details and constraint definitions.

Python API example

from qn_util.qn_network_builder import QnNetworkBuilder

builder = QnNetworkBuilder.from_poscar("POSCAR", "qn_config.json")
print(builder.get_qn_counts())
builder.write_analysis("sample")
builder.write_all("sample")

write_all generates analysis results and RMC input files. See example/ for example scripts and configuration.

Installation

pip install qn-util

Documentation

The tutorials cover Qn networks, FNC constraints, topology, JSON configuration, and possible extensions. The API Reference is generated from source docstrings.

Contents

• Tutorials
  • README0
  • RMC Topology / FNC Generator
  • Design Principles
  • Class Structure
  • Library Features
  • FNC and Topology in RMC_POT
  • Qn Network Analysis
  • Network Model
  • Definition of Qn
  • Analysis Procedure
  • 1. Extracting Atomic Species
  • 2. Central–Bridge Search
  • 3. Bridge–Second Search
  • 4. Identifying Bridging Atoms
  • 5. Determining Qn
  • Analysis Results
  • FNC (Fixed Neighbour Constraint)
  • Role of FNC in RMC_POT
  • Concept of FNC
  • FNC Generation in This Library
  • FNC Types
  • FNC Pairs
  • FNC File Structure
  • Pair Symmetry
  • Type Management
  • Limitations of FNC
  • Position in the Library
  • Topology (*.top)
  • Differences from FNC
  • Bonded Potentials in RMC_POT
  • Topology Structure
  • Approach Used by This Library
  • Bond Generation
  • Angle Generation
  • Bond Parameters
  • Angle Parameters
  • Atomic Information
  • Unit Topology
  • Network Topology
  • Unit Topology vs. Network Topology
  • Relationship to the SiO₂ Implementation
  • Role of RmcConstraintWriter
  • JSON Configuration File
  • Configuration Flow
  • network
  • Neighbor Search
  • second_use_first_network
  • Bond Parameters
  • Angle Parameters
  • Atomic Information
  • FNC Types
  • Role of JSON
  • SiO₂-Specific Settings
  • Applying the Library to Other Materials
  • Materials That Are Difficult to Handle
  • Design Philosophy
  • SiO₂ Implementation and Extension to Other Materials
  • SiO₂-Specific Components
  • 1. Definition of Qn
  • 2. SiO₄ Tetrahedra
  • 3. Bond Parameters
  • 4. Angle Parameters
  • General-Purpose Components
  • Applicable Materials
  • Future Extensions
  • Position of This Library
• qn_util
  • qn_util package