NetConvert

Script: netconvert.sh Package: ml Class: NetConvert.java

Converts neural network (.bbnet) files between different on-disk formats. Reads a network and writes it back out in the default format (A48 compressed) or decimal format. The weights are unchanged; this is a purely lossless format round-trip conversion, typically reducing file size by approximately 30% when converting from decimal to A48.

Basic Usage

netconvert.sh in=<old.bbnet> out=<new.bbnet>

NetConvert performs format conversion on neural network files. Input files in either decimal or A48 format are automatically detected. The output file is written in the default format (A48) unless explicitly changed with the a48 parameter. The conversion preserves all network weights exactly; no retraining or modification occurs.

Format Support

The tool automatically detects input format based on the file header (or assumes decimal for old headerless networks). Output format is controlled by the a48 parameter. A48 (Binary 2-bit Encoding) achieves roughly 30% size reduction compared to decimal text format while maintaining full precision for all weights.

Memory and Performance

NetConvert uses default Java memory settings (2GB heap) appropriate for typical neural network files. For very large networks, memory can be increased with the -Xmx parameter. Conversion speed depends primarily on file I/O and is generally very fast relative to network training time.

Parameters

NetConvert parameters control input/output file selection and output format encoding. All parameters use the standard BBTools format.

Required Parameters

in=<file>
Input neural network file (.bbnet). Can be in decimal format or A48 compressed format; the format is auto-detected from the file header. Aliases: net, netin.
out=<file>
Output neural network file (.bbnet). Will be written in the format specified by the a48 parameter. Alias: netout.

Format Control

a48=t
Write output network in A48 (compressed 2-bit) format. Default is true (A48 format). Set a48=f to write output in decimal format. A48 format provides approximately 30% size reduction while remaining fully lossless for network weights.

Output Control

overwrite=t
Permit overwriting the output file if it already exists. Default is true. Set overwrite=f to prevent accidental overwriting of existing files. Alias: ow.

Java Parameters

-Xmx<size>
Set maximum Java heap memory usage. Use format like -Xmx2g for 2 gigabytes or -Xmx1024m for 1024 megabytes. Default is 2000m (2 gigabytes). Increase for very large network files.
-da
Disable Java assertions. Used for performance tuning in production environments.

Usage Examples

Convert Decimal Network to A48 Format

Convert an older decimal-format network file to the compressed A48 format, reducing file size while preserving all network weights exactly:

netconvert.sh in=model_old.bbnet out=model_compressed.bbnet

This converts model_old.bbnet to A48 format by default, producing a file approximately 30% smaller than the original.

Convert A48 Network Back to Decimal

Convert a compressed A48 network back to human-readable decimal format for inspection or compatibility:

netconvert.sh in=model_compressed.bbnet out=model_decimal.bbnet a48=f

This reads the A48-format network and writes it in decimal format, making the weights human-readable while preserving exact numerical values.

Auto-Detect and Re-encode

Process multiple networks with automatic format detection, always outputting in A48 format:

netconvert.sh in=network1.bbnet out=network1_optimized.bbnet
netconvert.sh in=network2.bbnet out=network2_optimized.bbnet

Regardless of whether input files are decimal or A48, output files are always in A48 format, optimizing storage space across a network library.

Workflow Integration

Training to Production Pipeline

NetConvert is typically used after Train to optimize trained networks for storage and distribution. The workflow is:

  1. Train a neural network using Train (produces a network file)
  2. Convert the network to compressed format using NetConvert with a48=t
  3. Deploy the compressed network for use in production tools

Format Debugging and Compatibility

When network formats cause compatibility issues or uncertainty about encoding, use NetConvert to normalize files. Converting to decimal with a48=f and back to A48 provides a clean round-trip that validates the file and removes any format artifacts.

Support

For questions and support: