Metadata-Version: 2.4
Name: nznet
Version: 1.0.0
Summary: Python module for non-Zachariasen network analyses.
Author-email: Stephen Wilke <swilke@matsdev.com>, Jared Rafferty <jrafferty@matsdev.com>, Richard Weber <rweber@matsdev.com>
Maintainer-email: Jared Rafferty <jrafferty@matsdev.com>
Project-URL: Company Homepage, https://www.matsdev.com/
Project-URL: Documentation, https://www.matsdev.com/about-us.html
Project-URL: Repository, https://github.com/jraffertymdi/NZNET
Project-URL: Reference Publication, https://www.matsdev.com/news-publications.html
Keywords: connectedness,linkedness,material science
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.21
Requires-Dist: ase>=3.26.0
Requires-Dist: pymatgen>=2024.8.9
Requires-Dist: pandas>=2.3.3
Requires-Dist: PyYAML>=6.0
Dynamic: license-file

# 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`
3. Install Spyder (or other IDE)
    - `conda install -c conda-forge spyder`
4. Install Dependencies via pip(or conda) if needed
5. Install package via command line interface
    - `pip install nznet`
6. Download example folder to desired directory ([Package Install Examples](https://github.com/jraffertymdi/NZNET/tree/main/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.

```python
@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

```mermaid
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

```python
## 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](https://github.com/jraffertymdi/NZNET/tree/main/src/nznet/analysis)

| File |	Description |
|----|-------------|
|[calculator.py](https://github.com/jraffertymdi/NZNET/blob/main/src/nznet/analysis/calculator.py)| contains **functions for network analysis** of atomic structures |
|[Plotting.py](https://github.com/jraffertymdi/NZNET/blob/main/src/nznet/analysis/Plotting.py)| contains **functions to plot network metrics**, calls **calculator.py** functions |


### [Assets](https://github.com/jraffertymdi/NZNET/tree/main/src/nznet/assets)

| File |	Description |
|----|-------------|
|[read_data_files.py](https://github.com/jraffertymdi/NZNET/blob/main/src/nznet/assets/read_data_file.py)| contains functions for reading and validating input files. |
|[Save_plot.py](https://github.com/jraffertymdi/NZNET/blob/main/src/nznet/assets/Save_plot.py)| saves plots into /Python Plots/ (mm/dd/yy) folder in assets folder. |
|[Utility.py](https://github.com/jraffertymdi/NZNET/blob/main/src/nznet/assets/Utility.py)| builds neighbor lists, filters by cn, and has other auxiliary functions |

### [Definitions](https://github.com/jraffertymdi/NZNET/tree/main/src/nznet/definitions)

| File |	Description |
|----|-------------|
|[dataclass.py](https://github.com/jraffertymdi/NZNET/blob/main/src/nznet/definitions/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](https://github.com/jraffertymdi/NZNET/tree/main/src/nznet/tests)
| File |	Description |
|----|-------------|
|[test_atoms.py](https://github.com/jraffertymdi/NZNET/blob/main/src/nznet/tests/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](https://github.com/jraffertymdi/NZNET/tree/main/src/nznet/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. 














