# CDT-RS CLI Example Scripts
This directory contains shell scripts that demonstrate how to use the `cdt` command-line binary for simulation-oriented scenarios.
> **Current simulation status:** scripts that pass `--simulate` run the Metropolis-Hastings loop over the 2D CDT move kernels. Remove `--simulate` only when you
> want triangulation construction without Monte Carlo steps.
## Available Scripts
### 1. `basic_simulation.sh`
**Purpose**: Demonstrates a simple CDT simulation command. **Usage**:
```bash
./examples/scripts/basic_simulation.sh
```
**What it does**:
- Builds the cdt binary in release mode
- Builds a 4-vertices-per-slice, 5-timeslice command with 1000 requested MC steps
- Shows logging output for a short `--simulate` run
**Use this for**: First-time testing, verifying installation
### 2. `parameter_sweep.sh`
**Purpose**: Runs a systematic temperature-sweep command set. **Usage**:
```bash
./examples/scripts/parameter_sweep.sh
```
**What it does**:
- Tests temperatures from 0.5 to 3.0
- Requests 2000 MC steps for each temperature
- Saves individual logs to `sweep_results/`
- Runs each sweep point with `--simulate`
**Use this for**: Parameter exploration setup and early phase-transition analysis
### 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 current command runtime and setup overhead
- Generates performance summary report
- Saves results to `performance_results.txt`
**Use this for**: Construction and simulation scaling studies
## Prerequisites
### System Requirements
- Bash shell (zsh also works)
- `bc` calculator (for performance script)
- Sufficient memory for large triangulation runs
### 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_PER_SLICE=4
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_PER_SLICE=4
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 with custom parameters. Remove --simulate when you only want triangulation construction.
RUST_LOG=info ./target/release/cdt \
--vertices-per-slice 4 \
--timeslices 10 \
--temperature 1.5 \
--steps 3000 \
--simulate
echo "Custom command completed!"
```
## Expected Output
### Current `--simulate` Runs
Scripts that pass `--simulate` currently show:
- Build confirmation
- Progress messages
- Simulation logs (with `RUST_LOG=info`)
- Completed Metropolis-Hastings measurements when the sampled move applications remain valid
- A non-zero exit from the `cdt` command if configuration validation fails or an accepted move cannot be applied after bounded retries
### 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
Triangulation-only logs contain:
```text
[INFO] Dimensionality: 2
[INFO] Number of vertices: 32
[INFO] Number of timeslices: 8
[INFO] Topology: OpenBoundary
[INFO] Using trait-based backend system
[INFO] Triangulation created with 32 vertices, <edge-count> edges, <face-count> faces
[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 configuring CDT runs with the `cdt` binary.