CLI Reference

NLSQ provides a command-line interface for curve fitting workflows, batch processing, and system information.

Entry Points

Command

Description

nlsq

Main CLI entry point

nlsq-gui

Direct Qt GUI launcher

Global Options

nlsq --version         Show version and exit
nlsq -v, --verbose     Enable verbose output
nlsq --help            Show help and available commands

Commands

nlsq gui

Launch the interactive Qt desktop GUI for visual curve fitting.

nlsq gui

The GUI provides a 5-page workflow: Data Loading → Model Selection → Fitting Options → Results → Export. Requires the gui_qt extra:

pip install nlsq

nlsq fit

Execute single curve fit from a YAML workflow configuration.

Syntax:

nlsq fit <workflow.yaml> [OPTIONS]

Arguments:
  workflow.yaml        Path to workflow YAML configuration file

Options:
  --style PRESET       Override visualization style (publication, nature, science, presentation, minimal)
  -o, --output FILE    Override export.results_file path
  --stdout             Output results as JSON to stdout (for piping)

Examples:

# Basic fit
nlsq fit workflow.yaml

# Generate Nature-style figure
nlsq fit workflow.yaml --style nature

# Override output file
nlsq fit workflow.yaml --output results.json

# Output to stdout for piping
nlsq fit workflow.yaml --stdout

# Verbose mode
nlsq --verbose fit workflow.yaml

nlsq batch

Execute parallel batch fitting from multiple YAML workflow files.

Syntax:

nlsq batch <files...> [OPTIONS]

Arguments:
  files...             Paths to workflow YAML configuration files

Options:
  -s, --summary FILE      Path for aggregate summary file
  -w, --workers N         Maximum parallel workers (default: auto-detect)
  --continue-on-error     Continue processing on individual failures (default: true)

Examples:

# Multiple files
nlsq batch w1.yaml w2.yaml w3.yaml

# Using shell glob expansion
nlsq batch configs/*.yaml

# With worker limit and summary file
nlsq batch configs/*.yaml --workers 4 --summary batch_results.json

# Verbose mode
nlsq --verbose batch *.yaml

nlsq info

Display system and environment information including NLSQ version, Python version, JAX backend, GPU info, and available builtin models.

Syntax:

nlsq info
nlsq --verbose info    # More detailed output

Sample Output:

NLSQ Information
================
Version: 0.7.0
Python: 3.12.0
JAX: 0.8.2
Device: cuda:0 (NVIDIA RTX 4090)
Memory: 24.0 GB available

Builtin Models:
- linear, exponential_decay, exponential_growth
- gaussian, sigmoid, power_law, polynomial

nlsq config

Copy configuration templates to current directory to start a new project.

Syntax:

nlsq config [OPTIONS]

Options:
  --workflow          Copy only the workflow configuration template (workflow_config.yaml)
  --model             Copy only the custom model template (custom_model.py)
  -o, --output FILE   Custom output filename (only valid with --workflow or --model)
  -f, --force         Overwrite existing files without prompting

Examples:

# Copy both templates
nlsq config

# Workflow template only
nlsq config --workflow

# Model template only
nlsq config --model

# Custom filename for model template
nlsq config --model -o my_model.py

# Force overwrite existing files
nlsq config -f

Quick Reference

nlsq                    # Show help
nlsq gui                # Launch Qt GUI
nlsq fit w.yaml         # Single fit
nlsq batch *.yaml       # Batch fit
nlsq info               # System info
nlsq config             # Get templates

Workflow Configuration

The nlsq fit and nlsq batch commands use YAML workflow configurations. See Configuration Reference for the full configuration reference.

Minimal Example:

data:
  input_file: "data/experiment.csv"
  columns: { x: 0, y: 1 }
model:
  type: "builtin"
  name: "exponential_decay"
  auto_p0: true
export:
  results_file: "results.json"

Built-in Workflow Presets:

Preset

Description

standard

Standard curve_fit() with default tolerances (1e-8)

quality

Highest precision with multi-start (tolerances 1e-10)

fast

Speed-optimized with looser tolerances (1e-6)

large_robust

Chunked processing with multi-start for large datasets

streaming

AdaptiveHybridStreamingOptimizer for huge datasets

hpc_distributed

Multi-GPU/node configuration for HPC clusters (PBS)

Exit Codes

Code

Meaning

0

Success

1

General error (configuration, data loading, model, or fitting error)

Scripting Examples

Batch Processing with Shell:

#!/bin/bash
for config in configs/*.yaml; do
    nlsq fit "$config" || echo "Failed: $config"
done

Pipeline Integration:

# Fit and extract parameter with jq
nlsq fit workflow.yaml --stdout | jq '.popt[0]'

Parallel Batch with Custom Summary:

nlsq batch experiments/*.yaml \
    --workers 8 \
    --summary results/batch_summary.json

JSON Output Format

When using --stdout, results are output as JSON:

{
  "popt": [2.5, 10.2, 0.05],
  "pcov": [[0.01, 0.0, 0.0], [0.0, 0.09, 0.0], [0.0, 0.0, 0.0004]],
  "success": true,
  "message": "Optimization converged",
  "nfev": 42,
  "cost": 0.0025
}

See Also