### Live stdout Progress Example

Source: https://context7.com/thebitpusher/boxologic/llms.txt

Observe real-time progress updates during a packing analysis, showing iteration count, best volume percentage, and time.

```bash
# Run against the above file (doc/boxlist.txt)
boxologic -f doc/boxlist.txt

# Live stdout progress (updated in-place):
# VARIANT:     1; ITERATION (TOTAL):     1; BEST SO FAR: 100.000 %; TIME: 0
```

--------------------------------

### Boxologic Command-Line Interface Examples

Source: https://context7.com/thebitpusher/boxologic/llms.txt

Interact with Boxologic using command-line flags. Use `-h` for help, `-v` for version, and `-f` or `--inputfile` to specify the boxlist input file.

```bash
# Print help
boxologic -h
# Output:
# USAGE:
#   boxologic <option>
# OPTIONS:
#   [ -f|--inputfile ] <boxlist text file>   : Perform bin packing analysis
#   [ -v|--version ]                         : Print software version
#   [ -h|--help ]                            : Print this help screen
```

```bash
# Print version
boxologic -v
# Output: Boxologic version 0.01
```

```bash
# Run a packing analysis on a boxlist file
boxologic -f doc/boxlist.txt
```

```bash
# Long-form flag equivalent
boxologic --inputfile doc/boxlist.txt
```

--------------------------------

### Boxlist Input File Format Example

Source: https://context7.com/thebitpusher/boxologic/llms.txt

Define pallet dimensions on the first line, followed by box types. Each box line specifies label, three dimensions, and quantity.

```text
# Line 1: pallet X Y Z dimensions
# Subsequent lines: label  dim1  dim2  dim3  quantity
104, 96, 84
1. 70, 104, 24, 4
2. 14, 104, 48, 2
3. 40, 52, 36, 3
```

--------------------------------

### Visudat Output File Format Example

Source: https://context7.com/thebitpusher/boxologic/llms.txt

The visudat file format describes pallet dimensions and packed box coordinates. The first line contains pallet X Y Z dimensions, followed by lines for each packed box with its origin (cox coy coz) and dimensions (packx packy packz).

```text
# visudat format:
#   Line 1: pallet_x  pallet_y  pallet_z
#   Lines 2+: cox  coy  coz  packx  packy  packz
  104   96   84
    0    0    0  104   24   70
    0    0   70  104   48   14
    0   24    0  104   24   70
```

--------------------------------

### Select Best-Fitting Box with `find_box()` / `analyze_box()`

Source: https://context7.com/thebitpusher/boxologic/llms.txt

Iterates through unpacked boxes, testing orientations against available space. It identifies the best box fitting within the layer height and the best box for starting a sub-layer.

```c
// find_box(hmx, hy, hmy, hz, hmz)
//   hmx = max X space available
//   hy  = current layer thickness (target Y dimension)
//   hmy = remaining pallet Y height
//   hz  = tighter Z constraint (gap to neighbour)
//   hmz = looser Z constraint (remaining pallet Z)
//
// After find_box() returns:
//   boxi  > 0 → index of best box fitting within layer height
//   bboxi > 0 → index of best box that starts a sub-layer (layerinlayer)
//
// Example call site inside pack_layer() for Situation-1 (no neighbours):
//   lenx = smallestz->cumx;          // full X width available
//   lpz  = remainpz - smallestz->cumz;
//   find_box(lenx, layerthickness, remainpy, lpz, lpz);

```

--------------------------------

### Build Boxologic Binaries with Make

Source: https://context7.com/thebitpusher/boxologic/llms.txt

Use `make` commands to compile the Boxologic program. Options include building the standard binary, a debug version, running a demo, executing tests, or cleaning build artifacts.

```bash
# Build the boxologic binary
make
```

```bash
# Build a debug-symbol binary
make boxologic_debug
```

```bash
# Build and immediately run the bundled sample boxlist
make demo
```

```bash
# Run the full regression test suite against known-good results
make test
```

```bash
# Remove all build artifacts and generated output files
make clean
```

--------------------------------

### Generate Output Report with `report_results()`

Source: https://context7.com/thebitpusher/boxologic/llms.txt

Replays the best packing solution to generate a formatted text report and raw data for visualization. It also prints a summary to standard output.

```text
# Example output file: doc/boxlist.txt.out
---------------------------------------------------------------------------------------------
                                       *** REPORT ***
---------------------------------------------------------------------------------------------
ELAPSED TIME                                          : Almost 0 sec
TOTAL NUMBER OF ITERATIONS DONE                       : 1
BEST SOLUTION FOUND AT ITERATION                      : 1 OF VARIANT: 1
TOTAL NUMBER OF BOXES                                 : 6
PACKED NUMBER OF BOXES                                : 6
TOTAL VOLUME OF ALL BOXES                             : 838656
PALLET VOLUME                                         : 838656
BEST SOLUTION'S VOLUME UTILIZATION                    : 838656 OUT OF 838656
PERCENTAGE OF PALLET VOLUME USED                      : 100.000000 %
PERCENTAGE OF PACKED BOXES (VOLUME)                   : 100.000000 %
WHILE PALLET ORIENTATION                              : X=104; Y=96; Z= 84
---------------------------------------------------------------------------------------------
  NO: PACKSTA DIMEN-1  DMEN-2  DIMEN-3   COOR-X   COOR-Y   COOR-Z   PACKEDX  PACKEDY  PACKEDZ
---------------------------------------------------------------------------------------------
    1    1       70      104       24        0        0        0      104       24       70
    5    1       14      104       48        0        0       70      104       48       14
    ... 

 *** LIST OF UNPACKED BOXES ***

```

--------------------------------

### C: `execute_iterations()` Core Packing Loop

Source: https://context7.com/thebitpusher/boxologic/llms.txt

This C function iterates through all six pallet orientations, ranks candidate layer heights, and greedily packs boxes into layers. It tracks the best solution found based on packed volume percentage.

```c
// Internally called from main() after initialize().
// Orientation variants:
//   1: pallet (X, Y, Z)
//   2: pallet (Z, Y, X)
//   3: pallet (Z, X, Y)
//   4: pallet (Y, X, Z)
//   5: pallet (X, Z, Y)
//   6: pallet (Y, Z, X)
//
// Short-circuits immediately if 100% pallet fill is achieved (hundredpercent=1).
// After completion:
//   best_variant   → which orientation (1-6) produced the best result
//   best_iteration → which layer-height candidate index was best
//   number_packed_boxes → count of boxes successfully placed
```

--------------------------------

### Boxologic Regression Test Suite Commands

Source: https://context7.com/thebitpusher/boxologic/llms.txt

The test/run_all.sh script executes all .txt files in the test/ directory against boxologic. Key output metrics are compared against known-good results. Use SNAPSHOT=1 to update known-good files.

```bash
# Build and run all tests
make test
```

```bash
# Update all known-good snapshots with current output
SNAPSHOT=1 ./test/run_all.sh
```

```bash
# Run a single test manually and inspect the report
./boxologic -f test/dpp01.txt
cat test/dpp01.txt.out
```

--------------------------------

### Evaluate Candidate Layer Heights with `list_candidate_layers()`

Source: https://context7.com/thebitpusher/boxologic/llms.txt

This function evaluates potential layer heights based on box dimensions and scores them by how well boxes align. Results are stored globally and sorted.

```c
// Called at the start of each orientation variant in execute_iterations().
// Also called again in report_results() to replay the best solution.
//
// layers[1..layerlistlen].layerdim  → candidate layer thickness (short int)
// layers[1..layerlistlen].layereval → fit quality score (lower = better fit)
//
// After qsort with compute_layer_list(), layers[1] is the best candidate.

```

--------------------------------

### Fill a Layer with `pack_layer()`

Source: https://context7.com/thebitpusher/boxologic/llms.txt

Fills a horizontal layer using a scrap pad to track free space. It handles various gap situations and returns an error code on memory allocation failure. Sets `packing=0` when no more boxes fit.

```c
// Returns: 0 = success, 1 = malloc failure
//
// Key globals read:   layerthickness, remainpy, remainpz, pallet_x
// Key globals written: packedvolume, packednumbox, layerdone, layerinlayer
//
// Calls find_smallest_z() → find_box() → checkfound() → volume_check()
// in a tight while(1) loop until layerdone is set.

```

--------------------------------

### C: `read_boxlist_input()` Functionality

Source: https://context7.com/thebitpusher/boxologic/llms.txt

This C function parses the input file to set pallet dimensions (`xx`, `yy`, `zz`), total box count, and populate the `boxlist` array with box details. It handles file opening errors and missing first lines.

```c
// Called automatically from initialize().
// After read_boxlist_input() completes:
//   xx, yy, zz  → pallet dimensions
//   total_boxes → total number of individual box instances
//   boxlist[1..total_boxes] → each box's dim1/dim2/dim3/vol/n fields populated

// Example: for the doc/boxlist.txt input above
// xx=104, yy=96, zz=84
// total_boxes = 4+2+3 = 9 (box type 1: qty 4, type 2: qty 2, type 3: qty 3)
// boxlist[1].dim1=70, boxlist[1].dim2=104, boxlist[1].dim3=24, boxlist[1].vol=175,680
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.