11# LocalMath.jl
22
33LocalMath is a typed, bounded, conflict-aware language for local scientific
4- computation on CPU and GPU through one KernelAbstractions execution path.
4+ computation. It separates mathematical meaning from physical execution, then
5+ runs the validated computation on CPU or GPU through one
6+ KernelAbstractions execution path.
57
6- Start with [ Quick start] ( learn/localmath-quickstart.md ) , then use
7- [ Relations and storage] ( learn/localmath-relations.md ) and the
8- [ Scientific recipes] ( learn/localmath-recipes.md ) for complete models.
8+ Use LocalMath when a model needs explicit finite domains, bounded topology,
9+ storage ownership, publication conflicts, or ordered state evolution. Domain
10+ packages still own their physics, clocks, random-number semantics, solvers,
11+ transactions, checkpoints, and distributed policy.
12+
13+ ## Install
14+
15+ LocalMath is currently a pre-release package. Develop it directly from its
16+ repository:
17+
18+ ``` julia
19+ using Pkg
20+ Pkg. develop (url= " https://github.com/PraneethMerugu/LocalMath.jl" )
21+ ```
22+
23+ ## A complete computation
24+
25+ This periodic finite-difference law is ordinary typed Julia code. Descriptors
26+ state the mathematical problem; preparation associates them with concrete
27+ storage and an explicit backend.
28+
29+ ``` @example home
30+ using LocalMath, KernelAbstractions
31+
32+ cells = Space(6)
33+ u = Field(cells, Float32)
34+ laplacian = Field(cells, Float32)
35+
36+ law = @localmath i ∈ periodic(cells) begin
37+ laplacian[i] = u[i - 1] - 2f0 * u[i] + u[i + 1]
38+ end
39+
40+ prepared = @prepare (law; backend=KernelAbstractions.CPU()) begin
41+ u = Float32[1, 2, 4, 7, 11, 16]
42+ laplacian = allocate(0f0)
43+ end
44+
45+ wait(execute!(prepared))
46+ result = LocalMath.storage(prepared, laplacian)
47+ @assert result == Float32[16, 1, 1, 1, 1, -20]
48+ nothing
49+ ```
50+
51+ Caller arrays are borrowed exactly as supplied. ` allocate(...) ` requests
52+ explicit LocalMath-owned backend storage; omitted scientific storage is never
53+ guessed or allocated during warm execution.
54+
55+ ## Core vocabulary
56+
57+ | Concept | Responsibility |
58+ | :--| :--|
59+ | ` Space ` and ` Field ` | Finite domains and typed mathematical values |
60+ | ` Relation ` | Bounded reads and publications between spaces |
61+ | ` LocalLaw ` | Stages, gathers, equations, and publication semantics |
62+ | ` bind ` and ` plan ` | Storage validation and backend-independent lowering |
63+ | ` prepare ` / ` @prepare ` | Backend realization, workspace, and device storage |
64+ | ` execute! ` | Asynchronous KernelAbstractions submission returning an ` ExecutionReceipt ` |
965
1066## One architecture, from equation to device
1167
@@ -25,3 +81,22 @@ creating parallel representations:
2581` inspect ` and ` compilation_report ` project facts from those existing values;
2682execution never consumes a report. CPU and qualified GPU backends use the same
2783laws, validation, packed storage, and KernelAbstractions execution path.
84+
85+ LocalMath supports identity and structured relations, interior and periodic
86+ stencils, fixed and dynamic topology, deterministic or explicitly relaxed
87+ reductions, argmin/argmax resolution, bounded grouped collection, and finite
88+ ordered recurrence. Preparation validates topology, callable admission,
89+ aliasing, workspace, and backend support before submission. CPU and Metal are
90+ exercised by the package test suite; other providers are not claimed until
91+ independently qualified.
92+
93+ ## Continue from here
94+
95+ | Goal | Guide |
96+ | :--| :--|
97+ | Run the first model and understand initialization | [ Quick start] (@ref localmath-quickstart) |
98+ | Choose topology and bind scientific storage | [ Relations and storage] (@ref localmath-relations) |
99+ | See stencils, scatter, resolve, collect, and recurrence | [ Scientific recipes] (@ref localmath-recipes) |
100+ | Diagnose validation or execution failures | [ Troubleshooting] (@ref localmath-troubleshooting) |
101+ | Lower another scientific package into LocalMath | [ Writing a domain compiler] (@ref localmath-domain-compiler) |
102+ | Find the complete public and qualified interface | [ API reference] (@ref localmath-api) |
0 commit comments