nznet 1.0.0

Python module for non-Zachariasen network analyses.

nznet

This module performs non-Zachariasen network analyses as described in the publication [DOI pending]. These analyses include coordination number (CN), connectedness, linkedness, and bond valence sum distributions for atomic structure models.

It uses pymatgen lattice tools for handling periodic boundary conditions during neighbor searching and ASE read for file input.

Required Dependencies

Created and ran using Python v3.13.11

1. numpy >=1.21
2. pymatgen >=3.26.0
3. matplotlib >= 3.10.8
4. ASE >=3.26.0
5. PyYaml >=6.0
6. pandas >=2.3.3

IDE used: Spyder v6.1.0

Developed on Windows 11 Pro

Packaged Installation (PIP), Preferred

1. Create a new virtual env for the project (optional)
   • conda create -n project-env python=3.13
   • conda activate project-env
2. Install Spyder (or other IDE)
   • conda install -c conda-forge spyder
3. Install Dependencies via pip(or conda) if needed
4. Install package via command line interface
   • pip install nznet
5. Download example folder to desired directory (Package Install Examples)
   • run Demo_Main.py to confirm installation.

Local Installation (via GitHub)

1. Download the Repo
2. Create a new virtual env for the project.
   • conda create -n project-env python=3.13
   • conda activate project-env
3. Install Spyder (or other IDE)
   • conda install -c conda-forge spyder
4. Navigate to project root, i.e. the folder containing "“pyproject.toml” and "README"
5. Install dependencies in edit mode.
   • pip install -e .
6. Open/ launch Spyder
7. In src/nznet/examples folder, run Demo_Main.py to confirm installation.

Dependencies should automatically install with pip install -e .

---

Features

• Supports multiple network former atom types (e.g., Si, Al, B, Ti)

• Per–atom-type cutoff distances

• Per–atom-type coordination number filtering (e.g., [4]Al, [5]Al)

• Periodic boundary condition neighbor searches

• Oxygen coordination distributions

• Oxygen Fractions: free, nonbridging, bridging, triple bonded, quadruply bonded

• Network Linkedness: Corner, Edge, and Face Sharing

• Network connectedness (Kn)

• Bond valence sums

• Built-in plotting utilities for network analyses

• Command Line Interface

---

Code Structure Overview

RunConfig (Dataclass)

A container for all user-defined parameters required to run the analysis.

@dataclass
class RunConfig:
    NFatoms: List[str]
    rCut: List[float]
    cnRange: List[List[int]]
    xBox: float
    yBox: float
    zBox: float
    angle_alpha: float
    angle_beta: float
    angle_gamma: float
    vesta_import: bool
    input_file: Path
   

Parameters

Name	Description
NFatoms	Network former atom symbols
rCut	Neighbor cutoff radius per NF atom (Angstroms)
cnRange	Allowed coordination numbers for each NF atom
xBox, yBox, zBox	Lattice dimensions (Angstroms)
angle_alpha, beta, gamma	Lattice angles (degrees)
vesta_import	Use VESTA lattice conventions
input_file	Path to input file

---

RunSteps

Main driver class that is responsible for executing the analysis pipeline.

• Validates inputs
• Reads configurations
• Builds the lattice
• Constructs neighbor lists
• Computes network analyses
• Produces plots

---

Execution Flow

High-Level Flow Chart

flowchart TD

A[Create RunConfig] --> B[Validate Inputs]
B --> C[Read Structure File]
C --> D[Build Lattice]

D --> E{Loop Over Configurations}

E --> F[Create Atom Objects]

F --> G[Build NF-O Neighbor Lists]
G --> H[Filter NF by CN]
H --> I[Build O-NF Neighbor Lists]

I --> J[Compute O Coordination]
J --> K[Compute Linkedness]
K --> L[Compute Connectedness Kn]
L --> M[Compute Bond Valence Sum]

M --> E

E -->|if Finished| N[Aggregate Results]
N --> O[Generate Plots]
O --> P[Return Data via Getter Methods]

Example Code

## import main functions
from nznet.main import RunConfig,RunSteps,Utility
## import to get data file to read
from nznet.resources import get_input_file

## default input file directory is "/input_files" folder
input_file = get_input_file("as62appendAtomes.xyz")

## Creation of RunConfig Container
AS_CONFIG = RunConfig(
    NFatoms=["Si", "Al"],
    rCut=[2.15,2.15],
    cnRange=[[3,4,5],[4,5,6]],
    xBox=30.84,
    yBox=30.84,
    zBox=30.84,
    angle_alpha=90,
    angle_beta=90,
    angle_gamma = 90,
    vesta_import = True,
    input_file=input_file
)

## init Runsteps, with 10 steps
exp = RunSteps(AS_CONFIG,num_of_steps=10, save_plot=False, verbose= True)

## Run nznet
exp.run()

## useful functions to help analyze after a run. ##

atoms = exp.get_atoms() ## gets a list of dictionaries. Each entry of the list corresponds to a step's data

## each of the below commands has aggregate data from all steps ran. Must be ran after .run() call.
Ofracs = exp.get_oFracs()
KF = exp.get_connectedness()
links = exp.get_links()
bvs = exp.get_bond_valence_sum()

Execution and Getter Methods

Method	Description
run()	Executes full analysis pipeline
get_atoms()	Returns NF and O atom objects
get_ids()	Returns NF and O atom ID sets
get_oFracs()	Returns pandas DataFrame with columns ['O_CN', 'mean_fraction', 'std_fraction']
get_links()	Returns pandas Dataframe of Pair values and Link counts
get_connectedness()	Returns pandas DataFrame with columns ['KN_index','NF_type', 'mean', 'stdev']
get_bond_valence_sum()	Returns pandas DataFrame with columns ['NF_type', 'Kn', 'mean_bond_valence', 'stdev_bv']
check_neighborhood(atom_id)	Inspect neighbors and metrics for a specific atom

Architecture

Analysis

File	Description
calculator.py	contains functions for network analysis of atomic structures
Plotting.py	contains functions to plot network metrics, calls calculator.py functions

Assets

File	Description
read_data_files.py	contains functions for reading and validating input files.
Save_plot.py	saves plots into /Python Plots/ (mm/dd/yy) folder in assets folder.
Utility.py	builds neighbor lists, filters by cn, and has other auxiliary functions

Definitions

File	Description
dataclass.py	defines data classes that serve as containers for network former (NF) atoms and oxygen atoms objects, storing information used in network connectedness calculations.

Tests

File	Description
test_atoms.py	test suite for modular testing of functionality related to atoms objects

Command Line Interface

The command line interface uses config files (.yaml) that store user-defined parameters for a run of a given composition. They have a similar format to Runconfig dataclass, examples can be found in the RunConfigs folder.

Navigate to the project location src/nznet/ (or for pip install, Package Install Examples/) to run using a command line interface. Make sure that the virtual env is active.

Current Commands are as follows:

1. nznet --all
   • runs all config files in RunConfigs folder src/nznet/RunConfigs/
2. nznet --config RunConfigs/sillimanite.yaml
   • would run the "sillimantie" config file. Replace "sillimanite" with desired file.