### Activate and Verify CGCNN Environment

Source: https://github.com/txie-93/cgcnn/blob/master/README.md

Commands to activate the environment and verify the installation by accessing the help documentation for the main training and prediction scripts.

```bash
source activate cgcnn
python main.py -h
python predict.py -h
```

--------------------------------

### Install CGCNN Prerequisites via Conda

Source: https://github.com/txie-93/cgcnn/blob/master/README.md

This command creates a dedicated conda environment named 'cgcnn' and installs the necessary dependencies including Python, scikit-learn, PyTorch, and pymatgen.

```bash
conda upgrade conda
conda create -n cgcnn python=3 scikit-learn pytorch torchvision pymatgen -c pytorch -c conda-forge
```

--------------------------------

### Initialize and Use CrystalGraphConvNet Model (Python)

Source: https://context7.com/txie-93/cgcnn/llms.txt

Demonstrates how to initialize the CrystalGraphConvNet model for both regression and classification tasks, and perform a forward pass with dummy data. Requires PyTorch.

```python
from cgcnn.model import CrystalGraphConvNet
import torch

# Initialize model for regression
model = CrystalGraphConvNet(
    orig_atom_fea_len=92,    # Input atom feature dimension (from atom_init.json)
    nbr_fea_len=41,          # Bond feature dimension (from Gaussian expansion)
    atom_fea_len=64,         # Hidden atom feature dimension
    n_conv=3,                # Number of graph convolutional layers
    h_fea_len=128,           # Hidden feature dimension after pooling
    n_h=1,                   # Number of hidden layers after pooling
    classification=False     # Set True for classification tasks
)

# Initialize model for classification
classification_model = CrystalGraphConvNet(
    orig_atom_fea_len=92,
    nbr_fea_len=41,
    atom_fea_len=64,
    n_conv=3,
    h_fea_len=128,
    n_h=1,
    classification=True
)

# Forward pass (requires batched input from collate_pool)
# atom_fea: (N_total_atoms, orig_atom_fea_len)
# nbr_fea: (N_total_atoms, max_num_nbr, nbr_fea_len)
# nbr_fea_idx: (N_total_atoms, max_num_nbr)
# crystal_atom_idx: list of LongTensors mapping crystals to atoms

# Example with dummy data
N, M = 10, 12  # 10 atoms, 12 neighbors each
atom_fea = torch.randn(N, 92)
nbr_fea = torch.randn(N, M, 41)
nbr_fea_idx = torch.randint(0, N, (N, M))
crystal_atom_idx = [torch.arange(5), torch.arange(5, 10)]  # 2 crystals

output = model(atom_fea, nbr_fea, nbr_fea_idx, crystal_atom_idx)
print(f"Output shape: {output.shape}")  # (2, 1) for 2 crystals
```

--------------------------------

### Load and Run CGCNN Programmatically

Source: https://context7.com/txie-93/cgcnn/llms.txt

Demonstrates how to load a saved PyTorch checkpoint, reconstruct the model architecture, and run inference using a custom DataLoader. Includes a helper class for denormalizing model outputs.

```python
import torch
from cgcnn.data import CIFData, collate_pool
from cgcnn.model import CrystalGraphConvNet
from torch.utils.data import DataLoader

checkpoint = torch.load('model_best.pth.tar', map_location='cpu')
model_args = checkpoint['args']
dataset = CIFData('data/sample-regression')

model = CrystalGraphConvNet(orig_atom_fea_len=64, nbr_fea_len=41, atom_fea_len=model_args['atom_fea_len'], n_conv=model_args['n_conv'], h_fea_len=model_args['h_fea_len'], n_h=model_args['n_h'], classification=model_args['task'] == 'classification')
model.load_state_dict(checkpoint['state_dict'])
model.eval()

# Inference loop omitted for brevity
```

--------------------------------

### Train CGCNN Models via CLI

Source: https://context7.com/txie-93/cgcnn/llms.txt

Commands to initiate training for regression or classification tasks and resume from existing checkpoints. The process uses main.py and accepts various hyperparameters like epochs, batch size, and learning rate.

```bash
python main.py data/sample-regression --task regression --epochs 100 --batch-size 256 --lr 0.01 --lr-milestones 80 --optim Adam --atom-fea-len 64 --h-fea-len 128 --n-conv 3 --n-h 1 --train-ratio 0.8 --val-ratio 0.1 --test-ratio 0.1
python main.py data/sample-classification --task classification --train-size 5 --val-size 2 --test-size 3
python main.py data/sample-regression --resume checkpoint.pth.tar --epochs 50
```

--------------------------------

### Train CGCNN Model using main.py (Bash)

Source: https://context7.com/txie-93/cgcnn/llms.txt

Command-line instructions for training a CGCNN model on a custom dataset using the `main.py` script. Handles data splitting, model training, and checkpointing.

```bash
# Basic training with ratio-based data split
python main.py data/sample-regression \
    --train-ratio 0.6 \
    --val-ratio 0.2 \
    --test-ratio 0.2

# Training with explicit data sizes
python main.py data/sample-regression \
    --train-size 6 \
    --val-size 2 \
    --test-size 2
```

--------------------------------

### POST /model/initialize

Source: https://context7.com/txie-93/cgcnn/llms.txt

Initializes the CrystalGraphConvNet model for either regression or classification tasks.

```APIDOC
## POST /model/initialize

### Description
Initializes a new CrystalGraphConvNet instance. Configure the model for regression or classification by toggling the classification parameter.

### Method
POST

### Parameters
#### Request Body
- **orig_atom_fea_len** (int) - Required - Input atom feature dimension.
- **nbr_fea_len** (int) - Required - Bond feature dimension.
- **atom_fea_len** (int) - Required - Hidden atom feature dimension.
- **n_conv** (int) - Required - Number of graph convolutional layers.
- **h_fea_len** (int) - Required - Hidden feature dimension after pooling.
- **n_h** (int) - Required - Number of hidden layers after pooling.
- **classification** (bool) - Required - Set True for classification, False for regression.

### Request Example
{
  "orig_atom_fea_len": 92,
  "nbr_fea_len": 41,
  "atom_fea_len": 64,
  "n_conv": 3,
  "h_fea_len": 128,
  "n_h": 1,
  "classification": false
}
```

--------------------------------

### AtomCustomJSONInitializer for Element Features (Python)

Source: https://context7.com/txie-93/cgcnn/llms.txt

Loads element-specific feature vectors from a JSON file to provide initial atomic representations. Requires a JSON file with atomic numbers as keys and feature vectors as values.

```python
from cgcnn.data import AtomCustomJSONInitializer

# Initialize from JSON file
# atom_init.json format: {"1": [0, 1, 0, ...], "2": [0, 0, 0, ...], ...}
# Keys are atomic numbers, values are feature vectors

atom_init = AtomCustomJSONInitializer('data/sample-regression/atom_init.json')

# Get feature vector for an element (by atomic number)
hydrogen_fea = atom_init.get_atom_fea(1)   # Hydrogen (Z=1)
carbon_fea = atom_init.get_atom_fea(6)     # Carbon (Z=6)
iron_fea = atom_init.get_atom_fea(26)      # Iron (Z=26)

print(f"Hydrogen features: {hydrogen_fea.shape}")  # (92,)
print(f"Available elements: {len(atom_init.atom_types)}")

# Save and load state
state = atom_init.state_dict()
new_init = AtomCustomJSONInitializer('data/sample-regression/atom_init.json')
new_init.load_state_dict(state)
```

--------------------------------

### Prepare Dataset Directory Structure

Source: https://context7.com/txie-93/cgcnn/llms.txt

Defines the required file structure for custom datasets, including the id_prop.csv file and atom_init.json. Provides a Python script to generate the id_prop.csv file programmatically.

```python
import csv
crystal_data = [('crystal_1', -1.234), ('crystal_2', -0.567)]
with open('my_dataset/id_prop.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    for cif_id, target in crystal_data:
        writer.writerow([cif_id, target])
```

--------------------------------

### POST /data/initialize-atoms

Source: https://context7.com/txie-93/cgcnn/llms.txt

Loads element-specific feature vectors from a JSON file for atomic representation.

```APIDOC
## POST /data/initialize-atoms

### Description
Loads atomic embeddings from a JSON file using the AtomCustomJSONInitializer class.

### Method
POST

### Parameters
#### Request Body
- **filepath** (string) - Required - Path to the atom_init.json file.

### Request Example
{
  "filepath": "data/sample-regression/atom_init.json"
}
```

--------------------------------

### Predict Material Properties via CLI

Source: https://context7.com/txie-93/cgcnn/llms.txt

Uses the predict.py script to perform inference on new crystal structures using pre-trained model weights. Outputs are saved to a test_results.csv file.

```bash
python predict.py pre-trained/formation-energy-per-atom.pth.tar data/sample-regression
python predict.py pre-trained/band-gap.pth.tar data/sample-regression
python predict.py pre-trained/formation-energy-per-atom.pth.tar data/sample-regression --batch-size 128
```

--------------------------------

### GaussianDistance Feature Expansion (Python)

Source: https://context7.com/txie-93/cgcnn/llms.txt

Expands interatomic distances into Gaussian basis functions for smooth representation. Uses NumPy for distance arrays.

```python
import numpy as np
from cgcnn.data import GaussianDistance

# Initialize Gaussian distance filter
gdf = GaussianDistance(
    dmin=0,      # Minimum distance (Angstroms)
    dmax=8,      # Maximum distance (Angstroms)
    step=0.2,    # Step size for Gaussian centers
    var=None     # Variance (defaults to step if None)
)

# Expand a distance matrix
distances = np.array([[2.5, 3.0, 4.2],
                      [1.8, 2.9, 5.1]])

expanded = gdf.expand(distances)
print(f"Input shape: {distances.shape}")       # (2, 3)
print(f"Output shape: {expanded.shape}")       # (2, 3, 41) - 41 Gaussian bases
print(f"Number of Gaussian filters: {len(gdf.filter)}")
```

--------------------------------

### Create DataLoaders with Train/Val/Test Split - Python

Source: https://context7.com/txie-93/cgcnn/llms.txt

The get_train_val_test_loader function generates PyTorch DataLoaders, facilitating dataset splitting for training, validation, and testing. It supports splitting by ratios or exact sizes and requires a collate function. This is crucial for model evaluation.

```python
from cgcnn.data import CIFData, collate_pool, get_train_val_test_loader

dataset = CIFData(root_dir='data/sample-regression')

# Option 1: Split by ratios
train_loader, val_loader, test_loader = get_train_val_test_loader(
    dataset=dataset,
    collate_fn=collate_pool,
    batch_size=64,
    train_ratio=0.6,
    val_ratio=0.2,
    test_ratio=0.2,
    return_test=True,
    num_workers=0,
    pin_memory=False,
    train_size=None,
    val_size=None,
    test_size=None
)

# Option 2: Split by exact sizes
train_loader, val_loader, test_loader = get_train_val_test_loader(
    dataset=dataset,
    collate_fn=collate_pool,
    batch_size=64,
    return_test=True,
    num_workers=0,
    pin_memory=False,
    train_size=6,
    val_size=2,
    test_size=2,
    train_ratio=None,
    val_ratio=0.1,
    test_ratio=0.1
)

# Iterate through batches
for (atom_fea, nbr_fea, nbr_fea_idx, crystal_atom_idx), target, batch_cif_ids in train_loader:
    print(f"Batch atom features: {atom_fea.shape}")
    print(f"Batch targets: {target.shape}")
    print(f"Crystal IDs: {batch_cif_ids}")
    break
```

--------------------------------

### Implement Normalizer Class for Target Scaling

Source: https://context7.com/txie-93/cgcnn/llms.txt

This class provides methods to normalize and denormalize target tensors using PyTorch. It includes functionality to save and load normalization parameters, which is critical for maintaining consistency between training and inference stages.

```python
import torch

class Normalizer:
    """Normalize a Tensor and restore it later."""
    def __init__(self, tensor):
        self.mean = torch.mean(tensor)
        self.std = torch.std(tensor)

    def norm(self, tensor):
        return (tensor - self.mean) / self.std

    def denorm(self, normed_tensor):
        return normed_tensor * self.std + self.mean

    def state_dict(self):
        return {'mean': self.mean, 'std': self.std}

    def load_state_dict(self, state_dict):
        self.mean = state_dict['mean']
        self.std = state_dict['std']

# Usage during training
sample_targets = torch.tensor([1.0, 2.0, 3.0, 4.0, 5.0])
normalizer = Normalizer(sample_targets)

# Normalize for training
normalized = normalizer.norm(sample_targets)
print(f"Normalized: {normalized}")

# Denormalize predictions
predictions = torch.tensor([0.0, 0.5, 1.0])
denormalized = normalizer.denorm(predictions)
print(f"Denormalized: {denormalized}")

# Save/load with checkpoint
state = normalizer.state_dict()
new_normalizer = Normalizer(torch.zeros(1))
new_normalizer.load_state_dict(state)
```

--------------------------------

### Load Crystal Structures with CIFData Dataset - Python

Source: https://context7.com/txie-93/cgcnn/llms.txt

The CIFData class loads crystal structures from CIF files and converts them into graph representations. It handles atom features, neighbor lists, and bond features, preparing data for the neural network. Dependencies include PyTorch and specific data files like id_prop.csv and atom_init.json.

```python
from cgcnn.data import CIFData, collate_pool, get_train_val_test_loader

# Initialize dataset from a directory containing CIF files
# Required files in root_dir:
#   - id_prop.csv: CSV with columns [crystal_id, target_property]
#   - atom_init.json: JSON mapping element numbers to feature vectors
#   - *.cif: Crystal structure files named {crystal_id}.cif

dataset = CIFData(
    root_dir='data/sample-regression',
    max_num_nbr=12,      # Maximum number of neighbors per atom
    radius=8,            # Cutoff radius in Angstroms for neighbor search
    dmin=0,              # Minimum distance for Gaussian expansion
    step=0.2,            # Step size for Gaussian distance filter
    random_seed=123      # Seed for shuffling data
)

# Access a single sample
(atom_fea, nbr_fea, nbr_fea_idx), target, cif_id = dataset[0]

# atom_fea: torch.Tensor (n_atoms, atom_fea_len) - atom features
# nbr_fea: torch.Tensor (n_atoms, max_num_nbr, nbr_fea_len) - bond features
# nbr_fea_idx: torch.LongTensor (n_atoms, max_num_nbr) - neighbor indices
# target: torch.Tensor (1,) - target property value
# cif_id: str - crystal identifier

print(f"Dataset size: {len(dataset)}")
print(f"Atom features shape: {atom_fea.shape}")
print(f"Neighbor features shape: {nbr_fea.shape}")
```

--------------------------------

### POST /data/expand-distances

Source: https://context7.com/txie-93/cgcnn/llms.txt

Expands interatomic distances into a set of Gaussian basis functions.

```APIDOC
## POST /data/expand-distances

### Description
Uses the GaussianDistance class to transform raw distance matrices into smooth, differentiable Gaussian-expanded features.

### Method
POST

### Parameters
#### Request Body
- **dmin** (float) - Required - Minimum distance.
- **dmax** (float) - Required - Maximum distance.
- **step** (float) - Required - Step size for Gaussian centers.
- **distances** (array) - Required - Matrix of interatomic distances.

### Request Example
{
  "dmin": 0,
  "dmax": 8,
  "step": 0.2,
  "distances": [[2.5, 3.0], [1.8, 2.9]]
}
```

--------------------------------

### Implement ConvLayer for Graph Convolution (Python)

Source: https://context7.com/txie-93/cgcnn/llms.txt

Implements the graph convolutional operation that updates atom features by aggregating information from neighbors. Requires PyTorch.

```python
import torch
from cgcnn.model import ConvLayer

# Initialize convolutional layer
conv = ConvLayer(
    atom_fea_len=64,   # Dimension of atom features
    nbr_fea_len=41     # Dimension of bond features
)

# Input tensors
N, M = 10, 12  # 10 atoms, 12 neighbors each
atom_fea = torch.randn(N, 64)       # Atom features
nbr_fea = torch.randn(N, M, 41)     # Bond features for each neighbor
nbr_fea_idx = torch.randint(0, N, (N, M))  # Neighbor indices

# Apply convolution
atom_fea_out = conv(atom_fea, nbr_fea, nbr_fea_idx)
print(f"Input shape: {atom_fea.shape}")
print(f"Output shape: {atom_fea_out.shape}")  # Same as input: (N, 64)
```

--------------------------------

### Define CrystalGraphConvNet Model - Python

Source: https://context7.com/txie-93/cgcnn/llms.txt

The CrystalGraphConvNet class implements the core graph convolutional neural network architecture. It handles atom feature embedding, multiple graph convolutional layers, feature pooling, and final property prediction. This model is central to the CGCNN framework.

```python
import torch
from cgcnn.model import CrystalGraphConvNet
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.