# mechestim

> NumPy-compatible math primitives with FLOP counting. mechestim is NOT a drop-in NumPy replacement — every arithmetic operation is counted and charged against a FLOP budget.

## Getting Started

- [Installation](https://aicrowd.github.io/mechestim/getting-started/installation/index.md): Install mechestim and verify setup
- [Your First Budget](https://aicrowd.github.io/mechestim/getting-started/first-budget/index.md): Create your first FLOP budget

## How-To Guides

- [Migrate from NumPy](https://aicrowd.github.io/mechestim/how-to/migrate-from-numpy/index.md): Migrate existing NumPy code to mechestim
- [Use Einsum](https://aicrowd.github.io/mechestim/how-to/use-einsum/index.md): Einstein summation patterns and costs
- [Exploit Symmetry](https://aicrowd.github.io/mechestim/how-to/exploit-symmetry/index.md): Save FLOPs via symmetry detection
- [Use Linear Algebra](https://aicrowd.github.io/mechestim/how-to/use-linalg/index.md): Linear algebra operations and costs
- [Use FFT](https://aicrowd.github.io/mechestim/how-to/use-fft/index.md): FFT operations, real vs complex, and costs
- [Plan Your Budget](https://aicrowd.github.io/mechestim/how-to/plan-your-budget/index.md): Query FLOP costs before executing
- [Debug Budget Overruns](https://aicrowd.github.io/mechestim/how-to/debug-budget-overruns/index.md): Diagnose and fix budget overruns

## Concepts

- [FLOP Counting Model](https://aicrowd.github.io/mechestim/concepts/flop-counting-model/index.md): How FLOP costs are computed analytically
- [Operation Categories](https://aicrowd.github.io/mechestim/concepts/operation-categories/index.md): Free vs counted vs blocked operations
- [NumPy Compatibility Testing](https://aicrowd.github.io/mechestim/concepts/numpy-compatibility-testing/index.md): NumPy compatibility test suite coverage

## Architecture

- [Client-Server Model](https://aicrowd.github.io/mechestim/architecture/client-server/index.md): Client-server architecture for sandboxed execution
- [Running with Docker](https://aicrowd.github.io/mechestim/architecture/docker/index.md): Running mechestim with Docker and Docker Compose

## Development

- [Contributor Guide](https://aicrowd.github.io/mechestim/development/contributing/index.md): Repository layout, local workflows, and generated-doc rules

## API Reference

- [Counted Operations](https://aicrowd.github.io/mechestim/api/counted-ops/index.md): Operations that cost FLOPs
- [Free Operations](https://aicrowd.github.io/mechestim/api/free-ops/index.md): Operations that cost 0 FLOPs
- [Symmetric Tensors](https://aicrowd.github.io/mechestim/api/symmetric/index.md): SymmetricTensor for symmetry-aware savings
- [Linear Algebra](https://aicrowd.github.io/mechestim/api/linalg/index.md): Linear algebra module (SVD, Cholesky, QR, etc.)
- [FFT](https://aicrowd.github.io/mechestim/api/fft/index.md): FFT module (fft, rfft, fftn, etc.)
- [Random](https://aicrowd.github.io/mechestim/api/random/index.md): Random number generation (sampling is counted)
- [Polynomial](https://aicrowd.github.io/mechestim/api/polynomial/index.md): Polynomial operations
- [Window Functions](https://aicrowd.github.io/mechestim/api/window/index.md): Window functions (bartlett, hamming, etc.)
- [Budget](https://aicrowd.github.io/mechestim/api/budget/index.md): BudgetContext and OpRecord classes
- [FLOP Cost Query](https://aicrowd.github.io/mechestim/api/flops/index.md): Cost query functions (einsum_cost, svd_cost, etc.)
- [Path Optimizer](https://aicrowd.github.io/mechestim/api/opt-einsum/index.md): Path optimizer for einsum contractions
- [Errors](https://aicrowd.github.io/mechestim/api/errors/index.md): Exception and warning classes

## Reference

- [For AI Agents](https://aicrowd.github.io/mechestim/reference/for-agents/index.md): Guide for AI coding assistants — resources, rules, and common mistakes
- [Operation Audit](https://aicrowd.github.io/mechestim/reference/operation-audit/index.md): Complete 482-operation inventory with costs
- [FLOP Cost Cheat Sheet](https://aicrowd.github.io/mechestim/reference/cheat-sheet/index.md): Quick FLOP cost reference for all operations

## Troubleshooting

- [Troubleshooting](https://aicrowd.github.io/mechestim/troubleshooting/common-errors/index.md): Common errors and fixes

## Changelog

- [Changelog](https://aicrowd.github.io/mechestim/changelog/index.md): Release history and breaking changes