# 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.
