# opencsp

**Repository Path**: material-virtual-design/opencsp

## Basic Information

- **Project Name**: opencsp
- **Description**: OpenCSP is a comprehensive, open-source Python library for crystal structure prediction and optimization. It provides a flexible framework for exploring and discovering new crystal structures.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-11-27
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenCSP: Open-Source Crystal Structure Prediction

## Overview

OpenCSP is a comprehensive, open-source Python library for crystal structure prediction and optimization. It provides a flexible framework for exploring and discovering new crystal structures using advanced computational methods.

## Features

### Key Capabilities
- Multi-dimensional structure prediction (0D clusters, 2D surfaces, 3D crystals)
- Multiple global optimization algorithms
  - Random Search (via OpenCSP API)
  - Genetic Algorithm (GA)
  - Particle Swarm Optimization (PSO)
- Flexible computational engine integration
  - Support for multiple calculators: MatterSim, ASE EMT, M3GNet, CHGNet, MACE, etc.
  - Dynamic calculator switching via configuration
- Advanced structure generation and mutation strategies
- Composition and symmetry constraints
- Generation-by-generation data saving (JSON format)
- Energy evolution plotting and visualization

### Supported Dimensionalities
- 0D: Atomic clusters
- 2D: Surface structures
- 3D: Bulk crystal structures

## Installation

### Prerequisites
- Python 3.9+
- Dependencies:
  - NumPy
  - SciPy
  - ASE (Atomic Simulation Environment)
  - Pymatgen
  - PyYAML
  - Optional: PyXtal for advanced symmetry generation

### Install from source
```bash
git clone https://gitee.com/haidi-hfut/opencsp.git
cd opencsp
pip install -e .
```

### Optional Dependencies
```bash
pip install pyxtal torch pymatgen mattersim matplotlib
```

## Quick Start

### Command-Line Interface (CLI)

OpenCSP provides a convenient CLI with unified subcommands for running optimizations and plotting results. By default, all outputs are saved to the `results/` directory.

#### 1. Using Configuration File

Create a `config.yaml` file:
```yaml
calculator:
  type: mattersim
  model_file: examples/mattersim-v1.0.0-5M.pth
composition: Si4O8
searcher: random
population: 10
generations: 10
output_dir: results/  # Optional, defaults to results/
```

Run optimization:
```bash
opencsp run --config config.yaml
```

#### 2. Using Command-Line Arguments

**Random Search with ASE EMT Calculator (default output to results/):**
```bash
opencsp run \
  --calculator ase \
  --composition Cu2 \
  --population 8 \
  --generations 10
```

**Genetic Algorithm with MatterSim:**
```bash
opencsp run \
  --calculator mattersim \
  --model examples/mattersim-v1.0.0-5M.pth \
  --composition Si4O8 \
  --searcher ga \
  --population 10 \
  --generations 20 \
  --crossover-rate 0.8 \
  --mutation-rate 0.2
```

**PSO with Formula Units:**
```bash
opencsp run \
  --calculator mattersim \
  --model examples/mattersim-v1.0.0-5M.pth \
  --composition SiO2 \
  --formula-units 2 \
  --searcher pso \
  --population 12 \
  --generations 15
```

#### 3. Plotting Energy Evolution

After running optimization, visualize the results using the `plot` subcommand:

**Plot best energy evolution (default directory: results/):**
```bash
opencsp plot --output energy_evolution.png --best
```

**Plot all individuals with best and average:**
```bash
opencsp plot \
  --output energy_plot.png \
  --all \
  --best \
  --average
```

**Plot histogram for all generations (combined in one graph):**
```bash
opencsp plot \
  --output all_histogram.png \
  --histogram
```

**Plot histogram for a specific generation:**
```bash
opencsp plot \
  --generation 5 \
  --output gen5_histogram.png \
  --histogram
```

**Note:** You can also use `opencsp-plot` as an alias for backward compatibility.

### Python API

#### Basic Usage with Random Search

```python
from opencsp.api import OpenCSP
from ase.calculators.emt import EMT

# Create OpenCSP instance
csp = OpenCSP(random_seed=42)

# Run optimization
result = csp.optimize(
    composition={"Cu": 2},
    calculator=EMT(),
    dimensionality=3,
    population_size=8,
    steps=10,
)

print(f"Best fitness: {result.best_individual.fitness:.6f}")
print(f"Best energy: {result.best_individual.energy:.6f} eV/atom")
```

#### Using Genetic Algorithm

```python
from opencsp.api import OpenCSP
from opencsp.core.evaluator import Evaluator
from opencsp.searchers.ga.genetic import GA
from ase.calculators.emt import EMT

# Create calculator and evaluator
calculator = EMT()
evaluator = Evaluator(calculator=calculator)

# Create GA searcher
ga = GA(
    evaluator=evaluator,
    crossover_rate=0.8,
    mutation_rate=0.2,
    elitism=1,
)

# Create structure generator
csp = OpenCSP(random_seed=42)
generator = csp.create_structure_generator(
    composition={"Cu": 2},
    dimensionality=3,
)

# Run optimization
best = ga.run(
    generator,
    population_size=10,
    max_steps=20,
    output_dir="results/",  # Save each generation
)

print(f"Best energy: {best.energy:.6f} eV/atom")
print(f"Generation stats: {ga.generation_stats}")
```

## Output Files

### Default Output Directory

By default, OpenCSP saves all output files to the `results/` directory. You can override this by specifying `--output-dir` for the `run` command or `--directory` for the `plot` command.

### Generation-by-Generation JSON Files

OpenCSP automatically saves each generation to separate JSON files in the output directory (default: `results/`):
- `generation-0.json`: Initial population
- `generation-1.json`: After first generation
- `generation-2.json`: After second generation
- ...

Each file contains:
- Population data (individuals with structures, energies, fitness)
- Generation statistics (for GA: crossover/mutation counts)
- All data serialized using `monty.serialization.dumpfn` with `as_dict()` methods

### Final Results JSON

When using `--output-json`, a summary file is saved containing:
- Optimization parameters
- Best individual
- Final population
- Optimization history
- Generation statistics

### Plot Statistics JSON

When generating plots, OpenCSP also saves statistics to JSON files:
- For single generation histograms: `{output_name}.json` with generation statistics
- For all generations histograms: `{output_name}.json` with combined statistics including:
  - Per-generation statistics
  - Overall statistics (best, worst, average, median, std)
  - Summary across all generations

## Configuration File Format

See `examples/config.yaml` for a complete example. Key options:

```yaml
calculator:
  type: mattersim  # or ase, m3gnet, chgnet, mace, etc.
  model_file: path/to/model.pth
  relax: false

composition: Si4O8
formula_units: 1
dimensionality: 3
searcher: random  # or ga, pso
population: 10
generations: 10
seed: 42

output_dir: results/  # Save each generation (default: results/)
output_json: final_results.json  # Save final summary (optional)
log_level: INFO  # Logging verbosity
```

## Architecture Highlights

- **High-level API**: `OpenCSP.optimize()` orchestrates structure generators, evaluators, and populations
- **Searchers**: GA/PSO searchers under `opencsp/searchers/` with unified operation base classes
- **Structure Generators**: Handle random and symmetry-constrained generation
- **Evaluators**: Wrap calculators and manage constraint penalties
- **CLI Interface**: User-friendly command-line tools for running and visualizing optimizations
- **Data Serialization**: Uses Monty serialization for robust JSON output

## Contributing

### How to Contribute
1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

### Development Setup
```bash
git clone https://gitee.com/haidi-hfut/opencsp.git
cd opencsp
pip install -e .[dev]
pytest
```

## License

MIT License

## Citation

If you use OpenCSP in your research, please cite:
```
OpenCSP Development Team. (2025).
OpenCSP: Open-Source Crystal Structure Prediction Software.
Repository, https://gitee.com/haidi-hfut/opencsp
```

## Contact

- Email: haidi@hfut.edu.cn
- Repository: [https://gitee.com/haidi-hfut/opencsp](https://gitee.com/haidi-hfut/opencsp)

## Acknowledgments

- Developed with support from the scientific computing community
- Inspired by challenges in materials discovery and computational chemistry