{"id":35542495,"url":"https://github.com/projecttorreypines/fastinterpolations.jl","last_synced_at":"2026-04-09T06:01:06.581Z","repository":{"id":328387529,"uuid":"1114715780","full_name":"ProjectTorreyPines/FastInterpolations.jl","owner":"ProjectTorreyPines","description":"Fast N-dimensional interpolation package for Julia","archived":false,"fork":false,"pushed_at":"2026-04-02T01:40:21.000Z","size":61031,"stargazers_count":54,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-03T01:43:06.742Z","etag":null,"topics":["2d","3d","fast","high-performance","interpolation","interpolations","n-dimensional"],"latest_commit_sha":null,"homepage":"","language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ProjectTorreyPines.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-11T19:26:36.000Z","updated_at":"2026-04-02T01:31:41.000Z","dependencies_parsed_at":"2026-03-31T07:02:55.234Z","dependency_job_id":"896c7ddd-323b-465f-934f-c17a9a96429c","html_url":"https://github.com/ProjectTorreyPines/FastInterpolations.jl","commit_stats":null,"previous_names":["projecttorreypines/fastinterpolations.jl"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/ProjectTorreyPines/FastInterpolations.jl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProjectTorreyPines%2FFastInterpolations.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProjectTorreyPines%2FFastInterpolations.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProjectTorreyPines%2FFastInterpolations.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProjectTorreyPines%2FFastInterpolations.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ProjectTorreyPines","download_url":"https://codeload.github.com/ProjectTorreyPines/FastInterpolations.jl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProjectTorreyPines%2FFastInterpolations.jl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31588038,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-09T05:33:47.836Z","status":"ssl_error","status_checked_at":"2026-04-09T05:32:26.579Z","response_time":112,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2d","3d","fast","high-performance","interpolation","interpolations","n-dimensional"],"created_at":"2026-01-04T05:10:10.746Z","updated_at":"2026-04-09T06:01:06.575Z","avatar_url":"https://github.com/ProjectTorreyPines.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"![FastInterpolations.jl](docs/images/github_banner.png)\n\n[![version](https://juliahub.com/docs/General/FastInterpolations/stable/version.svg)](https://juliahub.com/ui/Packages/General/FastInterpolations)\n[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://projecttorreypines.github.io/FastInterpolations.jl/stable/)\n[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://projecttorreypines.github.io/FastInterpolations.jl/dev/)\n[![CI](https://github.com/ProjectTorreyPines/FastInterpolations.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/ProjectTorreyPines/FastInterpolations.jl/actions/workflows/CI.yml)\n[![codecov](https://codecov.io/github/projecttorreypines/fastinterpolations.jl/graph/badge.svg?token=RQ9RwaxeZF)](https://codecov.io/github/projecttorreypines/fastinterpolations.jl)\n[![Benchmark](https://img.shields.io/badge/benchmarks-Chart-yellowgreen)](https://projecttorreypines.github.io/FastInterpolations.jl/bench/)\n[![Aqua QA](https://juliatesting.github.io/Aqua.jl/dev/assets/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)\n[![code style: runic](https://img.shields.io/badge/code_style-%E1%9A%B1%E1%9A%A2%E1%9A%BE%E1%9B%81%E1%9A%B2-black)](https://github.com/fredrikekre/Runic.jl)\n\n# FastInterpolations.jl\n\nA high-performance **N-dimensional** interpolation package for Julia, optimized for **zero-allocation hot loops**.\n\n## Key Strengths\n\n- 🚀 **Fast**: Optimized algorithms that outperform other packages.\n- ✅ **Zero-Allocation**: No GC pressure on hot loops.\n- 🎯 **Explicit BCs**: Support custom physical boundary conditions.\n- 📐 **Analytic Derivatives \u0026 Integration**: Analytical differential operators (gradient, hessian, etc.) and exact spline integration.\n- 🌌 **Generic**: Supports **Complex** values and **AD (AutoDiff)** — ForwardDiff, Zygote, Enzyme.\n- 🧵 **Thread-Safe**: Lock-free concurrent access across multiple threads.\n\n## Supported Methods\n`FastInterpolations.jl` supports **five interpolation families** — four classical polynomial splines (**Constant**, **Linear**, **Quadratic**, **Cubic**) plus the **Local Cubic Hermite family** (Hermite / PCHIP / Cardinal / Akima), each with a native adjoint operator ($W^\\top \\bar{y}$) for gradient-based workflows.\n\n### Classical splines\n\n| Interpolation | Adjoint | Continuity | Best For |\n|:-------------|:--------|:-----------|:---------|\n| `constant_interp` | `constant_adjoint` | C⁻¹ | Step functions |\n| `linear_interp` | `linear_adjoint` | C⁰ | Fast, lightweight, no overshoot |\n| `quadratic_interp` | `quadratic_adjoint` | C¹ | Smooth derivatives at low cost |\n| `cubic_interp` | `cubic_adjoint` | C² | High-accuracy C² splines |\n\n### Local Cubic Hermite family\n\nOne cubic Hermite basis, four choices of slope rule. All C¹-continuous, O(1) per query, no global solve — each cell's slopes come from a small local stencil (or are supplied directly). ND adjoint support is on the roadmap.\n\n| Interpolation | Adjoint (1D) | Slope rule | Best For |\n|:-------------|:-------------|:-----------|:---------|\n| `hermite_interp`  | `hermite_adjoint`  | user-supplied                | Physics-informed, analytical derivatives |\n| `pchip_interp`    | `pchip_adjoint`    | Fritsch-Carlson (3-point)    | Monotone data (CDFs, physical bounds) |\n| `cardinal_interp` | `cardinal_adjoint` | Catmull-Rom with `tension`   | Animation, spline curves through control points |\n| `akima_interp`    | `akima_adjoint`    | Akima (5-point stencil)      | Noisy data, outlier-robust |\n\n📖 [Interpolation Overview](https://projecttorreypines.github.io/FastInterpolations.jl/dev/interpolation/overview/) \n📖 [Local Cubic Hermite](https://projecttorreypines.github.io/FastInterpolations.jl/dev/interpolation/local_hermite/) \n📖 [Adjoint Overview](https://projecttorreypines.github.io/FastInterpolations.jl/dev/adjoint/overview/)\n\n## Quick Start\n\n`FastInterpolations.jl` provides two primary API styles, plus a specialized **SeriesInterpolant** for multi-series data.\n\n### 1. One-shot API (Dynamic Data)\nBest when **`y` values change** every step, but the grid **`x` remains fixed**.\n\n```julia\nusing FastInterpolations\n\n# Define grid and query points\nx = range(0.0, 10.0, 100)   # source grid (100 points)\ny = sin.(x)                 # initial y data\n\n# Basic usage\ncubic_interp(x, y, 0.33) # return interpolated value at x=0.33\ncubic_interp(x, y, [0.11, 0.22, 0.33]) # return values at x=[0.11,0.22,0.33]\n\n# Advanced usage (in-place vector query)\nxq = range(0.0, 10.0, 500)  # query points  (500 points)\nout = similar(xq)           # pre-allocate output buffer\n\nfor t in 1:1000\n    @. y = sin(x + 0.01t)           # y values evolve each timestep\n    cubic_interp!(out, x, y, xq)    # zero-allocation ✅ (after warm-up)\nend\n```\n\n### 2. Interpolant API (Static Data)\nBest for **fixed lookup tables** where both `x` and `y` are constant.\n\n```julia\nitp = cubic_interp(x, y)       # pre-compute spline coefficients once\n\nresult = itp(5.5)              # evaluate at single point\nresult = itp(xq)               # evaluate at multiple points\n@. result = a * itp(xq) + b    # seamless broadcast fusion\n```\n\n### 2.1 SeriesInterpolant (Multiple Series)\nWhen multiple y-series share the same x-grid, wrap them with `Series(...)` to create a SeriesInterpolant. It leverages **SIMD** and **cache locality** for **\u003e10× faster** evaluation compared to looping over individual interpolants.\n\n```julia\nx = range(0, 10, 100)\ny_series = Series( sin.(x), cos.(x), tan.(x), exp.(-x) ) # 4 series, on the same grid\n\nsitp = cubic_interp(x, y_series)   # create SeriesInterpolant\nsitp(0.5)  # → 4-element Vector: [≈sin(0.5), ≈cos(0.5), ≈tan(0.5), ≈exp(-0.5)]\n```\n\nFor detailed usage and performance trade-offs, see the [API Selection Guide](https://projecttorreypines.github.io/FastInterpolations.jl/dev/guides/api_selection/).\n\n## Multi-Dimensional Interpolation\n`FastInterpolations.jl` supports 2D, 3D, and N-dimensional interpolation on **any rectilinear grid** (uniform or non-uniform). The API generalizes the 1D case by packing axis-specific information into **Tuples** — for example, where 1D takes `x`, ND takes `(x, y, z, ...)` for the grid, query points, and parameters.\nSee the [ND Interpolation Guide](https://projecttorreypines.github.io/FastInterpolations.jl/dev/nd/overview/) for details.\n```julia\nusing FastInterpolations\n\n# Define 2D rectilinear grid (can be non-uniform) and data\nx, y = [0.0, 0.2, 0.5, 1.0], range(0, 2π, 50)\ndata2D = [sin(xi) * cos(yi) for xi in x, yi in y]\nxq, yq = [0.1, 0.2], [0.3, 0.4] # query vectors\n\n# 1. One-shot API: (grid_tuple, data, query_tuple)\nval  = cubic_interp((x, y), data2D, (0.5, 0.3)) # single point\nvals = cubic_interp((x, y), data2D, (xq, yq))   # vector query\n\n# 2. Interpolant API: Precompute coefficients once\nitp = cubic_interp((x, y), data2D)\nitp((0.5, 0.3)) # scalar query\nitp((xq, yq)) # vector query\n```\n\n**Key Features:**\n- **Flexible Grids:** Supports both uniform and non-uniform rectilinear grids.\n- **Full Parity:** Every 1D feature (BCs, derivatives, extrapolation) works in ND via Tuples.\n- **Zero-Allocation:** Optimized tensor-product evaluation for high-performance loops.\n\n### Unified API: `interp` — Per-Axis Methods\nMix different interpolation methods per axis with the `interp` unified API:\n\n```julia\n# Cubic on x-axis, linear on y-axis\nitp = interp((x, y), data; method=(CubicInterp(), LinearInterp()))\nitp((0.5, 0.3))\ngradient(itp, (0.5, 0.3))  # analytical gradient\n\n# Zero-allocation one-shot (no interpolant created)\nval = interp((x, y), data, (0.5, 0.3); method=(CubicInterp(), LinearInterp()))\n```\n\nHomogeneous methods (all same type) auto-dispatch to the optimized type — no performance penalty.\n\n📖 [Unified API Guide](https://projecttorreypines.github.io/FastInterpolations.jl/dev/nd/unified_api/)\n\n### 2D Visualization Example\nComparison on a non-uniform 2D rectilinear grid for $f(x, y) = \\sin(2\\pi x) \\cos(2\\pi y)$. Cubic interpolation maintains high accuracy and captures extrema even on coarse, non-uniform grids. The gray dots in the image below represent the given node points (6x7 grid), and the dashed lines illustrate the grid structure.\n![2D Interpolation Example](docs/images/readme_2d_comparison.png)\n\n\n\n## Performance\n\nBenchmark comparison against [Interpolations.jl](https://github.com/JuliaMath/Interpolations.jl), [DataInterpolations.jl](https://github.com/SciML/DataInterpolations.jl), and [Dierckx.jl](https://github.com/JuliaMath/Dierckx.jl) for **cubic spline interpolation**.\n\u003c!-- BENCHMARK_VERSIONS_START --\u003e\n\u003e **Env:** Local · macOS 15.7.3 · Apple M1 Pro · Julia 1.12.5\u003cbr\u003e\n\u003e **Pkg:** FastInterpolations (v0.4.8) · Interpolations (v0.16.2) · DataInterpolations (v8.9.0) · Dierckx (v0.5.4)\n\u003c!-- BENCHMARK_VERSIONS_END --\u003e\n\n![One-Shot](docs/images/benchmark_oneshot_detail.png)\n\n\u003c!-- BENCHMARK_SPEEDUP_START --\u003e\n**Speedup:** (2.4 ~ 15.1)× vs `Interpolations.jl` · (8.5 ~ 24.1)× vs `DataInterpolations.jl` · (14.4 ~ 19.8)× vs `Dierckx.jl`\n\u003c!-- BENCHMARK_SPEEDUP_END --\u003e\n\nOne-shot (construction + evaluation) time per call with fixed grid size $n=100$. `FastInterpolations.jl` is significantly faster even on the first call (cache-miss), and becomes even faster on subsequent calls (cache-hit).\n\n## More Features\n\n### Analytic Derivatives\nExact 1st–3rd order derivatives from spline coefficients — no finite differences. ND interpolants support `gradient`, `hessian`, and `laplacian`.\n```julia\n# 1D example\ncubic_interp(x, y, 5.0; deriv=DerivOp(1))   # 1D: f'(x)\n\n# 2D example \nitp2d = cubic_interp((x, y), data2D)\n\npoint = (0.5, 1.0)                       # query point (x, y)\nitp2d(point; deriv=DerivOp(1, 0))        # ∂f/∂x\nitp2d(point; deriv=DerivOp(1, 1))        # ∂²f/∂x∂y (mixed partial)\ngradient(itp2d, point)                   # (∂f/∂x, ∂f/∂y)\nhessian(itp2d, point)                    # 2×2 Hessian matrix\n```\n📖 [1D Derivatives](https://projecttorreypines.github.io/FastInterpolations.jl/dev/interpolation/derivatives/) · [ND Derivatives](https://projecttorreypines.github.io/FastInterpolations.jl/dev/nd/derivatives/)\n\n### Analytic Integration\nExact definite integration from spline coefficients — no numerical quadrature.\n```julia\nitp = cubic_interp(x, y)\nintegrate(itp, 0.0, π)                       # 1D: ∫₀^π f(x) dx\n\nitp2d = cubic_interp((x, y), data2D)\nintegrate(itp2d, (0.0, 0.0), (1.0, 1.0))    # 2D: ∫∫ f dA over [0,1]²\nintegrate(itp2d)                              # 2D: full-domain integral\n```\n📖 [1D Integration](https://projecttorreypines.github.io/FastInterpolations.jl/dev/interpolation/integration/) · [ND Integration](https://projecttorreypines.github.io/FastInterpolations.jl/dev/nd/integration/)\n\n### Boundary Conditions\nRich type system for physical BCs — Neumann, periodic, polynomial fit, and custom per-endpoint.\n```julia\ncubic_interp(x, y, xq; bc=CubicFit())                        # cubic polynomial fit (default)\ncubic_interp(x, y, xq; bc=PeriodicBC())                      # C²-continuous periodic\ncubic_interp(x, y, xq; bc=BCPair(Deriv1(2.0), Deriv1(0.0)))  # Neumann: specify f' at each end\ncubic_interp(x, y, xq; bc=BCPair(Deriv1(2.0), Deriv2(0.0)))  # mixed: slope left, curvature right\n```\n📖 [Boundary Conditions Guide](https://projecttorreypines.github.io/FastInterpolations.jl/dev/boundary-conditions/overview/)\n\n### Extrapolation\nQueries outside the data domain throw `DomainError` by default. Use `Extrap()` to allow them:\n```julia\ncubic_interp(x, y; extrap=Extrap(:clamp))             # clamp to boundary value\ncubic_interp(x, y; extrap=Extrap(:extend))            # extend boundary polynomial\ncubic_interp(x, y; extrap=Extrap(:fill; fill_value=NaN)) # fill with constant value\n# also :wrap (periodic) and :none (default, throws DomainError)\n```\n📖 [Extrapolation Guide](https://projecttorreypines.github.io/FastInterpolations.jl/dev/extrapolation/) · \n\n### Search\nNon-uniform (`Vector`) grids require an interval search. The default `AutoSearch()` picks the best strategy per-call:\n```julia\nitp = linear_interp(x_vec, y_vec; search=AutoSearch())  # default, adapts per-call\nitp(0.5)          # scalar → binary search\nitp(sorted_xq)    # sorted detected → linear walk + binary fallback\nitp(rand_xq)      # random detected → binary search\nitp(0.5; search=BinarySearch())  # manual override (rarely needed)\n```\n📖 [Search Policies](https://projecttorreypines.github.io/FastInterpolations.jl/dev/guides/search/policies/)\n\n### Hints\nGive the search a positional hint to speed up lookup — enables O(1) sequential access (ODE solvers, streaming):\n```julia\nitp = cubic_interp(x, y)\nhint = Ref(1)  # grid interval index, updated automatically\nfor t in time_steps  # monotonic or streaming\n    val = itp(t; hint=hint)  # hint is reused \u0026 updated each call\nend\n```\n📖 [Using Hints](https://projecttorreypines.github.io/FastInterpolations.jl/dev/guides/search/hints/)\n\n**See also:** [Factory Functions](https://projecttorreypines.github.io/FastInterpolations.jl/dev/guides/factory_functions/) · [Complex Numbers](https://projecttorreypines.github.io/FastInterpolations.jl/dev/guides/complex_number_support/) · [AutoDiff](https://projecttorreypines.github.io/FastInterpolations.jl/dev/guides/autodiff_support/) · [Thread Safety](https://projecttorreypines.github.io/FastInterpolations.jl/dev/architecture/thread_safety/) · [Optim.jl Integration](https://projecttorreypines.github.io/FastInterpolations.jl/dev/guides/optimization/)\n\n## Documentation\n\nFor detailed guides on boundary conditions, extrapolation, and performance tuning, visit the [Documentation](https://projecttorreypines.github.io/FastInterpolations.jl).\n\n\n## License\nApache License 2.0\n\n## Contact\nMin-Gu Yoo [![Linkedin](https://i.sstatic.net/gVE0j.png)](https://www.linkedin.com/in/min-gu-yoo-704773230) (General Atomics)  yoom@fusion.gat.com","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojecttorreypines%2Ffastinterpolations.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprojecttorreypines%2Ffastinterpolations.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojecttorreypines%2Ffastinterpolations.jl/lists"}