From 8953dbffaa5cd5de4621736c92869cb2544617ff Mon Sep 17 00:00:00 2001
From: Gage <gage.bonner@gmail.com>
Date: Sat, 23 Nov 2024 14:29:54 -0600
Subject: [PATCH] app docs, bump version

---
 Project.toml      |  2 +-
 docs/make.jl      |  3 ++-
 docs/src/app.md   | 43 +++++++++++++++++++++++++++++++++++++++++++
 docs/src/index.md |  1 +
 4 files changed, 47 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/app.md

diff --git a/Project.toml b/Project.toml
index 67629a5..4cbd9b9 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,7 +1,7 @@
 name = "UlamMethod"
 uuid = "4cc20838-1966-48f0-823a-5def0ad5c24d"
 authors = ["Gage Bonner <gage.bonner@gmail.com>"]
-version = "0.7.11"
+version = "0.7.12"
 
 [deps]
 ArgCheck = "dce04be8-c92d-5529-be00-80e4d2c0e197"
diff --git a/docs/make.jl b/docs/make.jl
index 9802ba4..192b7f3 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -9,7 +9,8 @@ makedocs(
     pages = [
         "Home" => "index.md",
         "Advanced Usage" => "advanced.md",
-        "API" => "api.md",
+        "Making an App" => "app.md",
+        "API" => "api.md"
     ],
     warnonly = true
 )
diff --git a/docs/src/app.md b/docs/src/app.md
new file mode 100644
index 0000000..7b2be52
--- /dev/null
+++ b/docs/src/app.md
@@ -0,0 +1,43 @@
+# Compiling UlamMethod.jl Into a Standalone App
+
+## Creating The App
+
+This experimental feature allows you to compile `UlamMethod.jl` into a standalone executable that can be used independently of Julia. Currently, only 2D data are supported. Note that creating the app requires a julia installation.
+
+1. Create a folder where you want the app to be stored and `cd` into it. For this example, we'll use `UlamApp`.
+
+2. Clone [https://github.com/70Gage70/UlamMethod.jl](https://github.com/70Gage70/UlamMethod.jl) into `UlamApp`. If you use [GitHub CLI](https://cli.github.com/) this is accomplished quickly by: `gh repo clone 70Gage70/UlamMethod.jl`. 
+
+3. Run the following command from the terminal. This will compile the app, taking 5-10 minutes. It will also add the package [`PackageCompiler`](https://github.com/JuliaLang/PackageCompiler.jl/tree/master) to your main environment. Run `julia -e 'import Pkg; Pkg.rm("PackageCompiler")` afterwards if you don't want it any more.
+```
+julia -e 'import Pkg; Pkg.add("PackageCompiler"); Pkg.develop(path = "UlamMethod.jl"); using PackageCompiler, UlamMethod; create_app("UlamMethod.jl/", "UlamMethodCompiled")'
+```
+The path to the executable is now `.../UlamApp/UlamMethodCompiled/bin/UlamMethod`. This can e.g. be added to your PATH for convenient access.
+
+## Using The App
+
+The expected syntax is `./UlamMethod ARG1 ARG2 ... ARG9`, where each `ARG` is defined as follows
+
+- `ARG1`: The path to the file containing the input data. This expects a [`.mat`](https://github.com/JuliaIO/MAT.jl) file that contains the variables `"x0", "xT", "y0"` and `"yT"`.
+- `ARG2`: The file to write the output. This should also be a `.mat` file.
+- `ARG3`: The type of binner. Options are `[rec, tri, hex, vor]`.
+- `ARG4`: The number of bins.
+- `ARG5 - ARG8`: These args control the fraction of data taken to be in nirvana on each side of the rectangular boundary in the order `left, right, bottom, top`. 
+- `ARG9`: The reinjection algorithm. Options are `[data, stat, unif]`.
+
+
+### Example
+
+The following terminal command will generate some test data in the file `traj-test.mat`:
+
+```
+julia -e 'import Pkg; Pkg.activate(temp = true); Pkg.add(["UlamMethod", "MAT"]); using UlamMethod, MAT; traj = Trajectories(2, 1000); matwrite("traj-test.mat", Dict("x0" => traj.x0[1,:], "y0" => traj.x0[2,:], "xT" => traj.xT[1,:],"yT" => traj.xT[2,:]))'
+```
+
+We'll apply Ulam's method with 100 rectangular bins and `"data"` reinjection (the default). We'll let `2%` of the data be in nirvana on the left side of the boundary. The output file will be `ulam-out.mat`. Due to precompilation issues, the very first time you run the app, it will be slow.
+
+```
+./UlamMethod traj-test.mat ulam-out.mat rec 100 0.02 0.0 0.0 0.0 data
+```
+
+The output `.mat` file contains the transition probability matrix `"P"` as well as the vertices defining the associated bins `"bins_verts"`. Refer to the `"info"` field for more information regarding the format of the output.
\ No newline at end of file
diff --git a/docs/src/index.md b/docs/src/index.md
index 17d303f..b755dac 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -22,6 +22,7 @@ defined in a subset of $\mathbb{R}^N$, the essential goal of Ulam's method is to
 - Multiple 2D algorithms for partitioning to triangles, rectangles, hexagons and adaptively sized [Voronoi cells](https://en.wikipedia.org/wiki/Voronoi_diagram).
 - Multiple stochasticization algorithms.
 - One-line plotting conveniences in 2D for easy visualization.
+- (Experimental) Compile UlamMethod.jl into a [standalone executable](app) for usage independent of Julia.
 
 # Installation