# ChunkMark - AdvChkSys Benchmarking Tool

ChunkMark is a comprehensive benchmarking and diagnostic tool for the AdvChkSys chunk management library. It provides detailed performance metrics and memory usage analysis to help developers optimize their chunk-based applications.

## Features

- **Performance Benchmarking**: Measures chunk creation, access, and unloading speeds
- **Memory Analysis**: Tracks memory consumption patterns during chunk operations
- **Stress Testing**: Simulates high-load scenarios with rapid chunk cycling
- **Memory Scaling Tests**: Shows how memory usage scales with increasing chunk counts
- **Detailed Reporting**: Provides formatted tables and summaries of benchmark results

## Usage

```
ChunkMark.exe [options]
```

### Command Line Options

| Option | Description |
|--------|-------------|
| `--cpus=N` | Set the number of CPU threads to use (default: all available) |
| `--2d-chunks=N` | Number of 2D chunks to benchmark (default: 10000) |
| `--2d-size=N` | Size of 2D chunks (NxN) (default: 32) |
| `--3d-chunks=N` | Number of 3D chunks to benchmark (default: 500) |
| `--3d-width=N` | Width of 3D chunks (default: 16) |
| `--3d-height=N` | Height of 3D chunks (default: 16) |
| `--3d-depth=N` | Depth of 3D chunks (default: 16) |
| `--3d-size=N` | Set all 3D dimensions to N (overrides individual settings) |
| `--max-loaded=N` | Maximum chunks to keep in memory (default: 100000) |
| `--2d-only` | Run only 2D benchmarks |
| `--3d-only` | Run only 3D benchmarks |
| `--memory-test` | Run memory scaling tests |
| `--stress-test` | Run chunk cycling stress tests |
| `--verbose` | Show detailed memory information during tests |

### Examples

Basic benchmark with default settings:
```
ChunkMark.exe
```

Run only 2D benchmarks with 50,000 chunks of size 64x64:
```
ChunkMark.exe --2d-only --2d-chunks=50000 --2d-size=64
```

Run 3D benchmarks with custom dimensions:
```
ChunkMark.exe --3d-only --3d-chunks=100 --3d-width=32 --3d-height=128 --3d-depth=32
```

Run memory scaling tests with verbose output:
```
ChunkMark.exe --memory-test --verbose
```

## Benchmark Types

### Standard Benchmarks

The standard benchmarks measure three key operations:

1. **Creation**: Time to create and fill chunks with data
2. **Access**: Time to read all data from chunks
3. **Unload**: Time to unload chunks from memory

These benchmarks are run for both 2D and 3D chunks (unless limited by command line options).

### Memory Scaling Test

This test incrementally loads more chunks and measures memory consumption at each step. It helps visualize how memory usage scales with chunk count and calculates the average memory per chunk.

### Stress Test

The stress test rapidly cycles chunks in and out of the cache to test the LRU eviction mechanism and memory stability under high load. It's useful for identifying memory leaks or performance degradation during extended use.

## Output

ChunkMark provides formatted output with:

- Benchmark results in tabular format
- Memory usage statistics
- Performance metrics (chunks/second)
- Summary of all tests

In verbose mode, it also shows detailed memory snapshots before and after each operation.

## Memory Safety

ChunkMark includes memory safety checks to prevent out-of-memory errors. If a benchmark would require more memory than is safely available, ChunkMark will prompt for alternative parameters or skip the test.

## Interpreting Results

- **Creation Time**: Lower is better. Measures how quickly chunks can be created and filled.
- **Access Time**: Lower is better. Measures how quickly data can be read from chunks.
- **Unload Time**: Lower is better. Measures how quickly chunks can be removed from memory.
- **Memory Usage**: Lower is better for a given number of chunks.
- **Chunks/Second**: Higher is better. Derived metric showing throughput.

## System Requirements
- Windows, Linux, or macOS operating system
- .NET 5.0 or higher
- Sufficient memory for the requested benchmark parameters (e.g., 3D benchmark with 1024 chunks of size 384×384×384 would require approximately 54-60 GB of RAM) (e.g., 3D benchmark with 1000 chunks of size 32×32×32 would require approximately 125 MB of RAM)
- Math for 1024 chunks at a size of 384x384x384. 

### Memory Calculation
For 1024 chunks at a size of 384×384×384:
```python
# Calculate cells per chunk
cells_per_chunk = 384 × 384 × 384 = 56,623,104 cells

# Calculate total bytes
total_bytes = cells_per_chunk × 1024 chunks = 57,972,964,416 bytes

# Convert to GB
total_GB = total_bytes / 1024 / 1024 / 1024 = 54.2 GB

# Add 5-20% overhead for metadata, references, and system overhead
final_estimate = 54.2 GB × (1.05 to 1.20) = 56.9 to 65.0 GB
```