Documentation

Complete technical documentation for timetable-sa - a production-grade, generic Simulated Annealing optimization library for TypeScript.

Overview

This documentation provides comprehensive coverage of the timetable-sa package, organized to support practitioners at all levels—from first-time users to advanced researchers implementing domain-specific optimization systems. The reference sections are aligned with the current implementation in src/ so the docs can be used as an operational source of truth, not only as conceptual guidance.

Documentation Philosophy

this documentation prioritizes:

• Completeness: Every public API, configuration option, and internal mechanism documented
• Precision: Technical accuracy with mathematical formalism where appropriate
• Practicality: Working examples, configuration profiles, and troubleshooting guidance
• Extensibility: Clear extension points for custom constraints, move generators, policies, and diagnostics-driven tuning

Documentation Workflows

The documentation is structured around three primary user journeys:

1. Learn

Get started with the fundamentals and build your first working optimizer.

• Introduction - Library overview, capabilities, and design philosophy
• Installation - Setup instructions for Node.js and Bun environments
• Quick Start - Complete 5-step walkthrough from state to solution
• Core Concepts - Essential concepts: constraints, moves, fitness, phases, tabu search

Time to first solution: ~15 minutes

2. Configure

Tune solver behavior for production workloads and specific problem domains.

• Configuration Guide - Complete configuration reference with tuning strategies
• Algorithm and Runtime Behavior - Deep dive into phase lifecycles, acceptance rules, diagnostics, and reheating
• Examples - Domain-specific implementations and patterns
• Testing Guide - Comprehensive testing strategies for constraints, moves, and solver configurations

Recommended for: Production deployments, performance tuning, custom implementations

3. Integrate

Understand internals for advanced customization and system integration.

• Internal Architecture - System design, component interactions, and extension points
• API Reference - Complete API documentation with TypeScript signatures
• Migration Guide - Version migration instructions
• Troubleshooting - Common issues and diagnostic procedures

Recommended for: Library contributors, framework builders, research applications

Quick Navigation

By Task

By Experience Level

Beginner (New to optimization)

1. Introduction
2. Installation
3. Quick Start
4. Core Concepts

Intermediate (Building production systems)

1. Configuration Guide
2. Advanced Features
3. Testing Guide
4. Examples

Advanced (Research and extension)

1. Internal Architecture
2. API Reference
3. Source code (TypeScript with comprehensive JSDoc)

Reference Materials

Configuration Profiles

Pre-configured parameter sets for common scenarios (from Configuration Guide):

• Quick Start: Rapid prototyping, small problems
• Quality: Production optimization, high-quality solutions
• Fast: Time-constrained scenarios
• Custom: User-defined parameters

Mathematical Foundations

Key algorithms and mathematical concepts:

• Simulated Annealing: Boltzmann acceptance probability, geometric cooling
• Tabu Search: Short-term memory with aspiration criteria
• Adaptive Operator Selection: Hybrid and roulette-wheel strategies
• Multi-phase Optimization: Phase 1 (hard), Phase 1.5 (intensification), Phase 2 (soft)

See Advanced Features and Internal Architecture for formal specifications.

Contributing to Documentation

When contributing to this documentation:

1. Keep it accurate: Test all code examples before submitting
2. Be precise: Use exact TypeScript types and API signatures
3. Include context: Explain why, not just how
4. Maintain consistency: Follow existing formatting and structure
5. Consider the audience: Tailor technical depth to the intended reader

Document Conventions

Code Examples

All code examples are:

• Runnable: Can be copied and executed with minimal modification
• Complete: Include necessary imports and type definitions
• Type-safe: Valid TypeScript with proper type annotations
• Practical: Derived from real-world use cases

Mathematical Notation

Mathematical descriptions use:

• Pseudocode: Clear algorithmic descriptions
• Formal notation: Set theory, probability, and optimization notation where appropriate
• Complexity analysis: Big-O notation for performance characteristics

Cross-References

Related documentation is linked:

• Inline links: [Configuration Guide](/docs/configuration)
• Section anchors: [API Reference](/docs/api-reference#constrainttstate)
• See also sections at document conclusions

Getting Help

If you can't find what you need:

1. Check Troubleshooting for common issues
2. Review Examples for similar use cases
3. Read the source code (extensively commented JSDoc)

---

Documentation Version: 1.0.0
Last Updated: March 2026
Maintainer: Benjamin Naphtali