### A Pluto.jl notebook ###
# v0.14.5
using Markdown
using InteractiveUtils
# ╔═╡ d941d6c2-55bf-11eb-0002-35c7474e4050
using NiLang, Test
# ╔═╡ 2061b434-0ad1-46eb-a0c7-1a5f432bfa62
begin
twocol(left, right; llabel="forward", rlabel="backward") = HTML("
| $llabel |
$rlabel |
|
$(html(left))
|
$(html(right))
|
")
example(str) = HTML("""$str
""")
title1(str) = HTML("""'_'))>$str
""")
title2(str) = HTML("""'_'))>$str
""")
titleref(str) = HTML("""$str""")
using PlutoUI: TableOfContents
using Pkg
pkgversion(m::Module) = Pkg.TOML.parsefile(NiLang.project_relative_path("Project.toml"))["version"]
hightlight(str) = HTML("$str")
end;
# ╔═╡ 8c2c4fa6-172f-4dde-a279-5d0aecfdbe46
module M
using NiLang
# define two functions
function new_forward(x)
if x > 0
return x * 2
elseif x < 0
return x / 2
end
end
function new_backward(x)
if x > 0
return x / 2
elseif x < 0
return x * 2
end
end
# declare them as reversible to each other
@dual new_forward new_backward
# The following is need only when your function is differentiable
using NiLang.AD: GVar
function new_backward(x::GVar)
if x.x > 0
GVar(new_backward(x.x), x.g * 2)
elseif x.x < 0
GVar(new_backward(x.x), x.g / 2)
end
end
function new_forward(x::GVar)
if x.x > 0
GVar(new_forward(x.x), x.g / 2)
elseif x.x < 0
GVar(new_forward(x.x), x.g * 2)
end
end
end
# ╔═╡ 3199a048-7b39-40f8-8183-6a54cccd91b6
using BenchmarkTools
# ╔═╡ 0e1ba158-a6bc-401c-9ba7-ed78020ad068
using Base.Threads
# ╔═╡ a4e76427-f051-4b29-915a-fdfce3a299bb
html"""
"""
# ╔═╡ c2c7b4d4-f8c9-4ebf-8da2-0103f03136e7
md"# NiLang's (v$(pkgversion(NiLang))) Documentation
NiLang is a embeded domain specific language (eDSL) in Julia, so one need to install [Julia](https://julialang.org/) first. Before reading this documentation, you need to know basic Julia grammar, and how to install and use packages.
Also, it might be good to read the [README](https://github.com/GiggleLiu/NiLang.jl) first. In this tutorial, we focus on
* NiLang grammar and design patterns,
* Automatic differentiation based on reversible programming.
"
# ╔═╡ 12f07cc7-979c-43c3-9dc9-36ea1463c1f6
md"The symbols used in this notebook"
# ╔═╡ 611b577f-4722-42bf-8f8e-aeb2fb30be71
md"""
| symbol | meaning | how to type |
| ------- | --------- | ----------- |
| ← | allocate | \leftarrow + TAB |
| → | deallocate | \rightarrow + TAB |
| ↔ | exchange | \leftrightarrow + TAB |
| ∅ | empty variable | \emptyset + TAB |
| ~ | inverse | ~ |
"""
# ╔═╡ 605872cf-f3fd-462e-a2b1-7d1c5ae45efd
title1("Getting started")
# ╔═╡ fb3dee44-5fa9-4773-8b7f-a83c44358545
md"
After installing NiLang in a Julia REPL by typing `]add NiLang`, one can use NiLang and use the macro `@i` to define a reversible function ``f_1: (x, y) → (x+5y, y)``."
# ╔═╡ 70088425-6779-4a2d-ba6d-b0a34c8e93a6
@i @inline function f1(x, y; constant)
x += y * constant
end
# ╔═╡ af738f89-3214-429c-9c7d-18a6ea0d9401
f1(1.0, 2.0; constant=5.0) # call
# ╔═╡ 48d7ebc1-5def-4a57-9ec1-3fc370a4543f
(~f1)(11.0, 2.0; constant = 5.0) # uncall
# ╔═╡ f0e94247-f615-472b-8218-3fa287b38aa1
md"A NiLang function defines a ``\mathbb{R}^n\rightarrow\mathbb{R}^n`` (notice inputs and outputs have the same shapes) mapping, it can take both keyword and positional arguments, where positional arguments can only be used as constants. There is no `return` statement because this function returns input non-keyword variables automatically, it is forbiden to write `return` statement inside a NiLang function.
One can aslo put macros like `@inline` after NiLang's `@i` macro. NiLang's macro will render the body of the function first and pass it to other macros.
"
# ╔═╡ 2581aa33-1dc5-40b1-aa9f-6a11cc750c93
md"`x += y * constant` is an instruction that defines a bijective mapping ``\mathbb{R}^3\rightarrow\mathbb{R}^3``. All NiLang instructions change the variable inplace. Here, we accumulate the result to `x` rather than using `y *= constant` to modify the variable directly. This is because in a regular number system, one can easily use the zero element as the eraser to erase all information, which will cause irreversibility."
# ╔═╡ 60575978-081a-4bca-a3ed-2b51cd6abc92
md"One can differentiate a NiLang function with the `NiLang.gradient(f, args; iloss, kwargs...)` where `args` and `kwargs` are positional and keyword arguments for `f`, and `iloss` is the index of the loss variable."
# ╔═╡ f98305cb-4ba2-404a-a5c3-65510e059504
NiLang.AD.gradient(f1, (1.0, 2.0); iloss=1, constant=5.0)
# ╔═╡ e8cd6667-597f-458b-8465-1822e09a7891
md"Here, we specify the first variable as the one that stores the loss. We get
```math
\begin{cases}
\frac{\partial x+5y}{\partial x}=1\\
\frac{\partial x+5y}{\partial y}=5\\
\end{cases}
```
"
# ╔═╡ 20145d75-004a-4c2f-b7ff-c400ca846d42
let
content = md"""The above macro generates two functions, one is `f` and another is `~f` (or `Inv(f)`). The `x += y * constant` is translated to function `(x, y, constant) = PlusEq(*)(x, y, constant)`, where the function `PlusEq(*)` is bijective.
```julia
julia> using MacroTools
julia> MacroTools.prettify(@macroexpand @i function f(x, y; constant)
x += y * constant
end)
quote
$(Expr(:meta, :doc))
function $(Expr(:where, :(f(x, y; constant))))
hare = wrap_tuple(((PlusEq)(*))(x, y, constant))
x = hare[1]
y = hare[2]
constant = hare[3]
(x, y)
end
if (NiLangCore)._typeof(f) != _typeof(~f)
function $(Expr(:where, :((newt::_typeof(~f))(x, y; constant))))
boar = wrap_tuple(((MinusEq)(*))(x, y, constant))
x = boar[1]
y = boar[2]
constant = boar[3]
(x, y)
end
end
end
```
"""
HTML("How does the compiler work?
$(html(content))