Advanced User Tutorials

These tutorials are for developers and scientists who want to leverage NLSQ’s full API capabilities: custom optimization pipelines, protocol-based design, performance tuning, and extending the library.

Note

Prerequisites: Complete the Routine User Tutorials first. Understanding the 3-workflow system is essential before diving into the API layer.

Who This Guide Is For

• Developers building custom optimization workflows

• Scientists with specialized fitting requirements

• Researchers extending NLSQ for new algorithms

• Power users wanting maximum control

What You’ll Learn

• NLSQ’s internal architecture and design patterns

• How to use core API classes directly

• Factory functions and dependency injection

• The v0.6.4 orchestration component system

• Performance tuning and profiling

• Creating custom optimizers and extensions

• 1. Architecture Overview
  • 1.1. Package Overview
  • 1.2. Optimization Pipeline
  • 1.3. JAX Patterns
  • 1.4. Chapter Overview
  • 1.5. Package Structure
  • 1.6. Key Design Principles
• 2. Core APIs
  • 2.1. CurveFit Class
  • 2.2. LeastSquares Class
  • 2.3. TRF Optimizer
  • 2.4. Result Types
  • 2.5. Chapter Overview
  • 2.6. API Level Comparison
  • 2.7. Quick Examples
• 3. Factories and Dependency Injection
  • 3.1. Factory Functions
  • 3.2. Protocols
  • 3.3. Adapters
  • 3.4. Dependency Injection
  • 3.5. Chapter Overview
  • 3.6. Why Factories and DI?
  • 3.7. Quick Examples
• 4. Orchestration Components (v0.6.4)
  • 4.1. Orchestration Overview
  • 4.2. DataPreprocessor
  • 4.3. OptimizationSelector
  • 4.4. CovarianceComputer
  • 4.5. StreamingCoordinator
  • 4.6. Facades
  • 4.7. Chapter Overview
  • 4.8. Component Architecture
  • 4.9. Why Decomposition?
  • 4.10. Quick Examples
• 5. Custom Workflows
  • 5.1. Chapter Overview
  • 5.2. Quick Example
• 6. Performance Optimization
  • 6.1. Chapter Overview
  • 6.2. Performance Quick Tips
• 7. Numerical Stability
  • 7.1. Chapter Overview
  • 7.2. Stability Features
• 8. Extending NLSQ
  • 8.1. Chapter Overview
  • 8.2. Extension Points

Learning Path

#	Chapter	What You’ll Learn	Time
1	Architecture Overview	Package structure, optimization pipeline, JAX patterns	30 min
2	Core APIs	CurveFit, LeastSquares, TRF classes	45 min
3	Factories and Dependency Injection	Factory functions, protocols, dependency injection	30 min
4	Orchestration Components (v0.6.4)	v0.6.4 decomposed components	45 min
5	Custom Workflows	Build your own optimization pipelines	45 min
6	Performance Optimization	JIT caching, memory management, profiling	30 min
7	Numerical Stability	Numerical guards, SVD fallback, recovery	30 min
8	Extending NLSQ	Custom protocols, plugins, testing	30 min

Prerequisites

• Completed routine user tutorials

• Python experience (classes, decorators, type hints)

• Understanding of optimization concepts

• Familiarity with JAX (helpful but not required)

Quick Reference: API Levels

NLSQ provides multiple API levels:

High Level    fit() function
     │           │
     │           ▼
     │     CurveFit class
     │           │
     │           ▼
Mid Level  LeastSquares class
     │           │
     │           ▼
Low Level  TrustRegionReflective

Choose based on needs:

• fit(): Simple, automatic (routine users)

• CurveFit: Reusable, stateful fitting

• LeastSquares: Direct optimizer control

• TRF: Algorithm-level customization

Import Patterns

# High-level API
from nlsq import fit, curve_fit, CurveFit

# Core classes
from nlsq.core.least_squares import LeastSquares
from nlsq.core.trf import TrustRegionReflective

# Factories
from nlsq.core.factories import create_optimizer, configure_curve_fit

# Orchestration (v0.6.4+)
from nlsq.core.orchestration import (
    DataPreprocessor,
    OptimizationSelector,
    CovarianceComputer,
    StreamingCoordinator,
)

# Protocols
from nlsq.interfaces import (
    OptimizerProtocol,
    CurveFitProtocol,
    CacheProtocol,
)

# Facades
from nlsq.facades import (
    OptimizationFacade,
    StabilityFacade,
    DiagnosticsFacade,
)