Skip to content

Commit e5880dd

Browse files
Merge pull request #15 from PraneethMerugu/codex/github-pages-docs
Publish LocalMath documentation with GitHub Pages
2 parents 0f3bfbf + 24f1383 commit e5880dd

5 files changed

Lines changed: 134 additions & 4 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@ jobs:
9494
run: julia --project=. --startup-file=no -e 'using Pkg; Pkg.instantiate(); Pkg.test(; test_args=["--jobs=2"])'
9595

9696
docs:
97+
if: github.event_name == 'pull_request'
9798
runs-on: ubuntu-latest
9899
steps:
99100
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6

‎.github/workflows/docs.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
tags: ['*']
7+
workflow_dispatch:
8+
9+
concurrency:
10+
group: docs-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
env:
14+
JULIA_VERSION: '1.12.6'
15+
16+
jobs:
17+
docs:
18+
name: Build and publish
19+
runs-on: ubuntu-latest
20+
timeout-minutes: 30
21+
permissions:
22+
contents: write
23+
steps:
24+
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
25+
- uses: julia-actions/setup-julia@fa02766e078afaaf09b14210362cee14137e6a32 # v3
26+
with:
27+
version: ${{ env.JULIA_VERSION }}
28+
- uses: julia-actions/cache@a45e8fa8be21c18a06b7177052533149e61e9b38 # v3
29+
- name: Build and publish documentation
30+
env:
31+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
32+
LOCALMATH_DEPLOY_DOCS: ${{ github.event_name == 'push' || github.ref == 'refs/heads/main' }}
33+
run: julia --project=docs --startup-file=no -e 'using Pkg; Pkg.develop(path="."); Pkg.instantiate(); include("docs/make.jl")'

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@ prepared runtime. Planning and execution never consume inspection reports.
9797

9898
## Learn more
9999

100+
- [Published documentation](https://praneethmerugu.github.io/LocalMath.jl/)
100101
- [Ten-minute quick start](docs/src/learn/localmath-quickstart.md)
101102
- [Relations and storage](docs/src/learn/localmath-relations.md)
102103
- [Scientific recipes](docs/src/learn/localmath-recipes.md)

‎docs/make.jl‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,30 @@ makedocs(
4040
sitename = "LocalMath.jl",
4141
authors = "Praneeth Merugu",
4242
modules = [LocalMath],
43+
format = Documenter.HTML(
44+
prettyurls = true,
45+
canonical = "https://praneethmerugu.github.io/LocalMath.jl/",
46+
repolink = "https://github.com/PraneethMerugu/LocalMath.jl",
47+
edit_link = "main",
48+
size_threshold = nothing,
49+
size_threshold_warn = nothing,
50+
),
4351
doctest = true,
4452
warnonly = false,
4553
pagesonly = true,
4654
checkdocs = :exports,
4755
remotes = nothing,
4856
pages = pages,
4957
)
58+
59+
if get(ENV, "LOCALMATH_DEPLOY_DOCS", "false") == "true"
60+
get(ENV, "GITHUB_ACTIONS", "false") == "true" ||
61+
error("Documentation deployment is only permitted inside GitHub Actions")
62+
get(ENV, "GITHUB_EVENT_NAME", "") == "pull_request" &&
63+
error("Documentation deployment is forbidden for pull requests")
64+
deploydocs(
65+
repo = "github.com/PraneethMerugu/LocalMath.jl.git",
66+
devbranch = "main",
67+
push_preview = false,
68+
)
69+
end

‎docs/src/index.md‎

Lines changed: 79 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,67 @@
11
# LocalMath.jl
22

33
LocalMath 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;
2682
execution never consumes a report. CPU and qualified GPU backends use the same
2783
laws, 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

Comments
 (0)