# CDT-RS Command Line Interface Examples

This document provides examples for using the `cdt` binary, the command-line interface for Causal Dynamical Triangulations simulations.

## Basic Usage

The `cdt` binary accepts various command-line arguments to configure and run CDT simulations.

### Quick Start

```bash
# Basic 2D CDT simulation with default parameters
./target/release/cdt --vertices 10 --timeslices 5

# Run with custom temperature and steps
./target/release/cdt --vertices 20 --timeslices 10 --temperature 1.5 --steps 2000
```

## Command Line Arguments

### Required Arguments

- `--vertices <N>`: Number of vertices in the triangulation (minimum 3)
- `--timeslices <N>`: Number of time slices in the CDT foliation (minimum 1)

### Optional Simulation Parameters

- `--dimension <D>`: Dimensionality (2-3, default: 2)
- `--temperature <T>`: Temperature for Metropolis algorithm (default: 1.0)
- `--steps <N>`: Number of Monte Carlo steps (default: 1000)
- `--thermalization-steps <N>`: Thermalization steps before measurements (default: 100)
- `--measurement-frequency <N>`: Take measurement every N steps (default: 10)

### Physics Parameters

- `--coupling-0 <κ₀>`: Coupling constant for vertices (default: 1.0)
- `--coupling-2 <κ₂>`: Coupling constant for triangles (default: 1.0)
- `--cosmological-constant <λ>`: Cosmological constant (default: 0.1)

### Additional Options

- `--simulate`: Run full Monte Carlo simulation (default: true; pass `--simulate false` to only generate the triangulation without running Monte Carlo steps)

## Example Usage Scenarios

### 1. Small Test Simulation

```bash
# Quick test with minimal parameters
./target/release/cdt --vertices 5 --timeslices 2 --simulate
```

**Expected Output:**

- Creates a 5-vertex, 2-timeslice triangulation
- Runs default 1000 Monte Carlo steps
- Reports simulation statistics

### 2. Medium-Scale Physics Study

```bash
# Medium triangulation for physics exploration  
./target/release/cdt \
  --vertices 50 \
  --timeslices 10 \
  --temperature 1.2 \
  --steps 5000 \
  --thermalization-steps 500 \
  --measurement-frequency 25 \
  --simulate
```

**Use Case:** Study phase transitions or scaling behavior

### 3. High-Temperature Simulation

```bash
# High temperature (classical limit)
./target/release/cdt \
  --vertices 30 \
  --timeslices 8 \
  --temperature 10.0 \
  --steps 3000 \
  --simulate
```

**Use Case:** Explore classical geometry limit

### 4. Low-Temperature Simulation

```bash
# Low temperature (quantum regime)
./target/release/cdt \
  --vertices 25 \
  --timeslices 12 \
  --temperature 0.5 \
  --steps 8000 \
  --thermalization-steps 1000 \
  --simulate
```

**Use Case:** Study quantum fluctuations and crumpled phase

### 5. Custom Physics Parameters

```bash
# Modified coupling constants
./target/release/cdt \
  --vertices 40 \
  --timeslices 8 \
  --coupling-0 0.8 \
  --coupling-2 1.2 \
  --cosmological-constant 0.05 \
  --simulate
```

**Use Case:** Explore modified gravity or different action formulations

### 6. Triangulation-Only Mode

```bash
# Generate triangulation without running Monte Carlo simulation
./target/release/cdt --vertices 100 --timeslices 20 --simulate false
```

**Use Case:** Generate initial configurations for other analysis tools

## Advanced Usage Patterns

### Batch Processing with Shell Scripts

Create a script to run parameter sweeps:

```bash
#!/bin/bash
# parameter_sweep.sh

for temp in 0.5 1.0 1.5 2.0 2.5; do
    echo "Running simulation at temperature $temp"
    ./target/release/cdt \
        --vertices 30 \
        --timeslices 10 \
        --temperature $temp \
        --steps 2000 \
        --simulate \
        > "results_T${temp}.log" 2>&1
done
```

### Performance Testing

```bash
# Large simulation for performance testing
./target/release/cdt \
  --vertices 200 \
  --timeslices 25 \
  --steps 10000 \
  --measurement-frequency 100 \
  --simulate
```

### Logging and Output

Enable detailed logging:

```bash
# Set log level for detailed output
RUST_LOG=debug ./target/release/cdt --vertices 10 --timeslices 5 --simulate

# Log only errors and warnings
RUST_LOG=warn ./target/release/cdt --vertices 50 --timeslices 10 --simulate

# Save output to file
./target/release/cdt --vertices 25 --timeslices 8 --simulate > simulation.log 2>&1
```

## Expected Output Format

### Successful Run

```text
[INFO] Dimensionality: 2
[INFO] Number of vertices: 10
[INFO] Time slices: 5
[INFO] Starting CDT simulation with backend...
[INFO] Temperature: 1.0
[INFO] Total steps: 1000
[INFO] Thermalization steps: 100
[INFO] Simulation completed in 45.23ms
[INFO] CDT simulation completed successfully
```

### Error Cases

```bash
# Invalid parameters
./target/release/cdt --vertices 2 --timeslices 1
# Error: vertices must be >= 3

# Unsupported dimension
./target/release/cdt --vertices 10 --timeslices 5 --dimension 4
# Error: unsupported dimension
```

## Performance Considerations

### Memory Usage

- Small (≤20 vertices): <10 MB
- Medium (20-100 vertices): 10-100 MB
- Large (100+ vertices): 100+ MB

### Runtime

- Test simulations (1000 steps): seconds
- Physics studies (10000+ steps): minutes
- Large systems: hours

### Optimization Tips

1. **Use release builds** for performance: `cargo build --release`
2. **Adjust measurement frequency** for long runs
3. **Monitor memory** for large vertex counts
4. **Use appropriate thermalization** (typically 10-20% of total steps)

## Troubleshooting

### Common Issues

1. **Binary not found**

   ```bash
   cargo build --release
   ./target/release/cdt --help
   ```

2. **Insufficient memory**
   - Reduce vertex count or steps
   - Monitor system resources

3. **Slow performance**
   - Ensure using release build
   - Check system load
   - Consider reducing measurement frequency

4. **Parameter validation errors**
   - Check minimum values (vertices ≥ 3, timeslices ≥ 1)
   - Verify dimension is 2 or 3

## Integration with Other Tools

### Data Analysis

```bash
# Pipe output to analysis tools
./target/release/cdt --vertices 50 --timeslices 10 --simulate | \
  python analysis_script.py
```

### Automation

```bash
# Use in makefiles or CI/CD
make run-simulation: 
 ./target/release/cdt --vertices $(VERTICES) --timeslices $(SLICES) --simulate
```

## Help and Documentation

```bash
# Display all available options
./target/release/cdt --help

# Version information  
./target/release/cdt --version
```

This CLI interface provides a powerful way to explore CDT physics and test different simulation parameters efficiently from the command line.
