perceptrono

Perceptron making, training and solving CLI util. Based on Synaptic project

Installation

In dir ./install find executable file matching your system and run it. Reopen terminal. Command perceptrono will be available in terminal. Alternatively read CLI Usage paragraph.

For installation for Node.js use npm npm i perceptrono or npm i -g perceptrono for global installation.

CLI Usage

The command called via CLI has the following format: <path-to-perceptrono-bin-file|perceptrono> <cli-params> where:

Bin files:

In case of correct installation you don't need to specify bin file and can use perceptrono command instead. Alternatively you can find all bin files located in the ./bin directory relative to the package root. Available bin files:

• perceptrono-x64 (Linux)
• perceptrono-x64 (Windows)
• perceptrono-x64 (macOS)
• For specific Node.js versions, build from source with 'pkg' util

CLI Parameters:

Model Operations:

• --loadModel path/to/model.json - loads a model from the specified path
• --makeModel [2,2,1] - creates a perceptron with the specified structure
• --makeModel path/to/schema.json - creates a perceptron with the specified structure

Resolution Operations:

• --resolve [2,2.1,-1] - Runs the loaded/created neural network with the specified input parameters
• --resolve path/to/input.json - Runs the loaded/created neural network with the specified input parameters
• --resolve [[0,1],[1,0],[0,0],[1,1]] - Batch resolution with multiple inputs (new!)
• --saveResult path/to/file.json - saves the solution to the specified file
• --printResult - if specified, prints the solution to the console

Training Operations:

• --train path/to/input.json - loads a training dataset in JSON format {input: number[], output: number[]}[] and trains using it
• --rate 0.1 - specifies learning-rate (default 0.1)
• --iterations 100000 - maximum training iterations (if not specified, defaults to 100,000)
• --error 0.01 - minimum error to stop training (optional)

Testing Operations (new!):

• --test path/to/test-data.json - tests the model with test dataset in JSON format {input: number[], output: number[]}[]
• --test [{"input":[0,1],"output":[1]},...] - tests the model with inline test data

Saving Operations:

• --saveModel path/to/model.js - saves the final model to the specified path (if empty, defaults to either the loaded model path or throws an error)

Either the --loadModel or --makeModel parameter must be specified, as well as either --resolve, --train, --test or --info.

Examples:

Training:

perceptrono --loadModel "./model.json" --train "./dataset.json" --rate 0.1 --error 0.01

Single Resolution:

perceptrono --loadModel "./model.json" --resolve "[0,1]" --printResult

Batch Resolution (new!):

perceptrono --loadModel "./model.json" --resolve "[[0,1],[1,0],[0,0],[1,1]]" --printResult

Testing (new!):

perceptrono --loadModel "./model.json" --test "./test-data.json" --printResult

Node usage

The package exports two main functions:

loadCliOpts() Loads and parses command line parameters.

import { loadCliOpts } from "perceptrono";
const options = loadCliOpts();

run(options) Performs neural network operations based on the provided parameters.

import { run, loadCliOpts } from "perceptrono";

// Option 1: Using command line parameters
const cliOptions = loadCliOpts();
await run(cliOptions);

// Option 2: Direct parameter passing
await run({
    makeModel: "[2, 4, 1]",
    train: "./dataset.json",
    rate: 0.3,
    iterations: 20000,
    saveModel: "./trained-model.json"
}); 

// Total schema of input options
// export interface InputOptions {
//     // Main operations
//     loadModel?: string;
//     makeModel?: string;
//     resolve?: string;
//     test?: string;           // NEW: Testing functionality
//     saveResult?: string;
//     printResult: boolean;
//     train?: string;
//     saveModel?: string;
//     
//     // Training params
//     rate: number;
//     iterations: number;
//     error?: number;
//     
//     // Engine and env
//     bin: BinType;
// }

Node CLI Adapter

The CLI Adapter module provides a high-level JavaScript/TypeScript interface for interacting with the perceptrono CLI utility programmatically. Instead of manually constructing command-line arguments, this module offers clean, typed functions that handle the underlying CLI execution, parameter formatting, and output parsing. The module exposes four main functions: resolvePerceptron for performing inference with a trained model (now supporting batch operations), trainPerceptron for model training with customizable parameters, createPerceptron for initializing new neural network architectures, and testPerceptron for comprehensive model evaluation that returns average error metrics across test cases. All functions support flexible binary path specification and return Promises for asynchronous operation, making them ideal for integration into larger applications, automated pipelines, or testing environments where programmatic control over the perceptrono CLI is required.

// Single resolution
export declare function resolvePerceptron(
    pathToPerceptron: string, 
    dataOrPathToData: string | number[] | number[][], 
    pathToBin: string
): Promise<InputData>;

export declare function trainPerceptron(
    pathToPerceptron: string, 
    pathToTrainData: string, 
    trainingOptions: {
        rate?: number;
        iterations?: number;
        error?: number;
    }, 
    pathToBin: string, 
    pathToSaveTrainedPerceptron?: string | null
): Promise<void>;

export declare function createPerceptron(
    pathToPerceptron: string, 
    layers: number[], 
    pathToBin: string
): Promise<void>;

export declare function testPerceptron(
    pathToPerceptron: string, 
    dataOrPathToData: string | InputOutput[], 
    pathToBin: string
): Promise<{
    err: number;
}>;

// InputOutput type
export interface InputOutput {
    input: number[];
    output: number[];
}

CLI Adapter Usage Examples:

import { resolvePerceptron, trainPerceptron, testPerceptron, createPerceptron } from "perceptrono";

// Single resolution
const singleResult = await resolvePerceptron("./model.json", [0, 1], "./bin/perceptrono-x64");
console.log(singleResult.data); // [0.85]

// Batch resolution (NEW!)
const batchResult = await resolvePerceptron("./model.json", [[0,1], [1,0], [0,0], [1,1]], "./bin/perceptrono-x64");
console.log(batchResult.data); // [[0.85], [0.92], [0.15], [0.08]]

// Testing with inline data (NEW!)
const testData = [
    { input: [0, 1], output: [1] },
    { input: [1, 0], output: [1] },
    { input: [0, 0], output: [0] },
    { input: [1, 1], output: [0] }
];
const testResult = await testPerceptron("./model.json", testData, "./bin/perceptrono-x64");
console.log(`Test error: ${testResult.err}`);

// Testing with file (NEW!)
const testResult2 = await testPerceptron("./model.json", "./test-data.json", "./bin/perceptrono-x64");

New Features

1. Batch Resolution

Now you can process multiple inputs at once using batch resolution:

• Pass 2D arrays to --resolve parameter
• Get results for all inputs in single operation
• Improved performance for bulk processing

2. Model Testing

Comprehensive model evaluation functionality:

• Test models with dedicated test datasets
• Calculate average error across all test cases
• Support for both file-based and inline test data
• Integration with CLI adapter for programmatic testing

3. Enhanced CLI Adapter

• Updated resolvePerceptron to support both single and batch operations
• Improved testPerceptron function with better error handling
• Consistent return types across all functions
• Better TypeScript support

Testing

Node.js

# Training
node ./js/exec --makeModel [2,4,1] --train ./test-data/xor-train-data.json --rate 0.01 --iterations 100000 --saveModel ./test-data/saved.json

# Single resolution
node ./js/exec --loadModel ./test-data/saved.json --resolve [0,1] --printResult

# Batch resolution (NEW!)
node ./js/exec --loadModel ./test-data/saved.json --resolve "[[0,1],[1,0],[0,0],[1,1]]" --printResult

# Testing (NEW!)
node ./js/exec --loadModel ./test-data/saved.json --test ./test-data/xor-test-data.json --printResult

Bin linux x64

# Training
./bin/perceptrono-x64 --makeModel [2,4,1] --train ./test-data/xor-train-data.json --rate 0.01 --iterations 100000 --saveModel ./test-data/saved.json

# Single resolution
./bin/perceptrono-x64 --loadModel ./test-data/saved.json --resolve [0,1] --printResult

# Batch resolution (NEW!)
./bin/perceptrono-x64 --loadModel ./test-data/saved.json --resolve "[[0,1],[1,0],[0,0],[1,1]]" --printResult

# Testing (NEW!)
./bin/perceptrono-x64 --loadModel ./test-data/saved.json --test ./test-data/xor-test-data.json --printResult

Author

Anatoly Starodubtsev [email protected]

License

MIT