# CDT-RS CLI Example Scripts
This directory contains shell scripts that demonstrate how to use the `cdt` command-line binary for various simulation scenarios.
## Available Scripts
### 1. `basic_simulation.sh`
**Purpose**: Demonstrates a simple CDT simulation run **Usage**:
```bash
./examples/scripts/basic_simulation.sh
```
**What it does**:
- Builds the cdt binary in release mode
- Runs a basic simulation (10 vertices, 5 timeslices, 1000 MC steps)
- Shows logging output and success confirmation
**Use this for**: First-time testing, verifying installation
### 2. `parameter_sweep.sh`
**Purpose**: Runs systematic temperature sweep for phase transition studies **Usage**:
```bash
./examples/scripts/parameter_sweep.sh
```
**What it does**:
- Tests temperatures from 0.5 to 3.0
- Runs 2000 MC steps for each temperature
- Saves individual logs to `sweep_results/`
- Provides summary of successful runs
**Use this for**: Physics studies, phase transition analysis, parameter exploration
### 3. `performance_test.sh`
**Purpose**: Benchmarks CDT performance across different system sizes **Usage**:
```bash
./examples/scripts/performance_test.sh
```
**What it does**:
- Tests small to extra-large system configurations
- Measures runtime and calculates throughput
- Generates performance summary report
- Saves results to `performance_results.txt`
**Use this for**: Performance analysis, scaling studies, optimization validation
## Prerequisites
### System Requirements
- Bash shell (zsh also works)
- `bc` calculator (for performance script)
- Sufficient memory for large simulations
### Build Requirements
- Rust toolchain (stable)
- All project dependencies available
## Quick Start
1. **Make scripts executable** (already done):
```bash
chmod +x examples/scripts/*.sh
```
2. **Run basic simulation**:
```bash
./examples/scripts/basic_simulation.sh
```
3. **Try a parameter sweep**:
```bash
./examples/scripts/parameter_sweep.sh
```
## Script Customization
### Modifying Parameters
Each script has configuration variables at the top that you can easily modify:
**basic_simulation.sh**:
```bash
# Edit the simulation parameters in the script
VERTICES=10
TIMESLICES=5
STEPS=1000
TEMPERATURE=1.0
```
**parameter_sweep.sh**:
```bash
# Modify temperature range or fixed parameters
TEMPERATURES=(0.5 0.8 1.0 1.2 1.5 2.0 2.5 3.0)
VERTICES=20
TIMESLICES=8
STEPS=2000
```
**performance_test.sh**:
```bash
# Add or modify system size configurations
TEST_CONFIGS=(
"10 5 1000" # Small
"20 8 2000" # Medium
"50 10 3000" # Large
"100 15 5000" # Extra Large
"200 20 10000" # Custom large config
)
```
### Creating Custom Scripts
Template for new scripts:
```bash
#!/bin/bash
set -e # Exit on error
echo "=== Custom CDT Script ==="
# Build the binary
cargo build --release
# Run simulation with custom parameters
RUST_LOG=info ./target/release/cdt \
--vertices 25 \
--timeslices 10 \
--temperature 1.5 \
--steps 3000 \
--simulate
echo "Custom simulation completed!"
```
## Expected Output
### Successful Runs
Scripts will show:
- Build confirmation
- Progress messages
- Simulation logs (with RUST_LOG=info)
- Success confirmation
- Results summary (for sweep/performance scripts)
### Error Handling
Scripts include error checking for:
- Build failures
- Binary not found
- Simulation crashes
- Invalid parameters
## Integration Examples
### Makefile Integration
```makefile
.PHONY: run-basic run-sweep run-performance
run-basic:
./examples/scripts/basic_simulation.sh
run-sweep:
./examples/scripts/parameter_sweep.sh
run-performance:
./examples/scripts/performance_test.sh
```
### CI/CD Integration
```yaml
# Example GitHub Actions step
- name: Run CDT performance tests
run: |
./examples/scripts/performance_test.sh
# Upload results artifact
```
### Data Analysis Pipeline
```bash
# Chain with analysis tools
./examples/scripts/parameter_sweep.sh && python analyze_results.py sweep_results/
```
## Output Files
### Generated by Scripts
- `sweep_results/`: Directory with individual simulation logs
- `performance_results.txt`: Performance benchmark data
- Various log files depending on script configuration
### Log Format
Simulation logs contain:
```text
[INFO] Dimensionality: 2
[INFO] Number of vertices: 20
[INFO] Time slices: 8
[INFO] Starting CDT simulation with backend...
[INFO] Temperature: 1.0
[INFO] Total steps: 2000
[INFO] Thermalization steps: 200
[INFO] Simulation completed in 45.23ms
[INFO] CDT simulation completed successfully
```
## Troubleshooting
### Common Issues
1. **Permission denied**:
```bash
chmod +x examples/scripts/*.sh
```
2. **Command not found**:
- Ensure you're in the project root directory
- Run `cargo build --release` first
3. **bc command not found** (macOS):
```bash
brew install bc
```
4. **Memory issues**:
- Reduce vertex counts in scripts
- Monitor system resources
### Performance Tips
- Use release builds (scripts do this automatically)
- Adjust measurement frequency for long runs
- Monitor memory usage for large systems
- Run on systems with adequate RAM
## Related Documentation
- [`docs/CLI_EXAMPLES.md`](../../docs/CLI_EXAMPLES.md): Comprehensive CLI usage guide
- [`examples/basic_cdt.rs`](../basic_cdt.rs): Library usage examples
- [`benches/README.md`](../../benches/README.md): Benchmarking documentation
These scripts provide a practical starting point for exploring CDT physics and conducting computational studies with the cdt binary.