cogentcore · kkoreilly · Jun 30, 2025 · Jun 20, 2025 · Jun 21, 2025 · Jun 21, 2025
diff --git a/docs/content/browser.md b/docs/content/browser.md
@@ -0,0 +1,6 @@
++++
+Categories = ["Lab"]
++++
+
+See `examples/planets` and `examples/simstats` for example uses of the **Browser** graphical interface. Go API docs: [[doc:lab.Browser]]
+
diff --git a/docs/content/cluster.md b/docs/content/cluster.md
@@ -0,0 +1,6 @@
++++
+Categories = ["Stats"]
++++
+
+**Cluster** computes agglomerative clustering. Go docs: [[doc:stats/cluster]]
+
diff --git a/docs/content/datatree.md b/docs/content/datatree.md
@@ -0,0 +1,8 @@
++++
+Categories = ["Lab"]
++++
+
+**DataTree** provides a [core/filetree](https://cogentcore.org/core/filetree) with support for standard data types, including viewing a [[tensorfs]] virtual filesystem, as part of a data [[Browser]].
+
+Go API docs: [[doc:lab.DataTree]]
+
diff --git a/docs/content/glm.md b/docs/content/glm.md
@@ -0,0 +1,6 @@
++++
+Categories = ["Stats"]
++++
+
+**glm** computes generalized linear models. Go docs: [[doc:stats/glm]]
+
diff --git a/docs/content/goal.md b/docs/content/goal.md
@@ -0,0 +1,36 @@
+**Goal** is the _Go augmented language_ with support for two additional modes, in addition to standard Go:
+
+* [[shell|$ shell mode $]] that operates like a standard command-line shell (e.g., `bash`), with space-separated elements and standard shell functionality including input / output redirection. Goal automatically detects most instances of shell mode based on the syntax of the line, but it can always be explicitly indicated with surrounding `$`s.
+
+* [[math|# math mode #]] that supports Python-like concise mathematical expressions operating on [[tensor]] elements.
+
+Here is an example of shell-mode mixing Go and shell code:
+
+```goal
+for i, f := range goalib.SplitLines($ls -la$) {  // ls executes, returns string
+    echo {i} {strings.ToLower(f)}              // {} surrounds Go within shell
+}
+```
+
+where Go-code is explicitly indicated by the `{}` braces.
+
+Here is an example of math-mode:
+```goal
+# x := 1. / (1. + exp(-wts[:, :, :n] * acts[:]))
+```
+
+You can also intermix math within Go code:
+```goal
+for _, x := range #[1,2,3]# {
+    fmt.Println(#x**2#)
+}
+```
+
+Goal can be used in an interpreted mode by using the [yaegi](https://github.com/traefik/yaegi) Go interpreter (and can be used as your shell executable in a terminal), and it can also replace the standard `go` compiler in command-line mode, to build compiled executables using the extended Goal syntax.
+
+A key design feature of Goal is that it always _transpiles directly to Go_ in a purely syntactically driven way, so the output of Goal is pure Go code.
+
+Goal can also be used in conjunction with [[gosl]] to build programs that transparently run on GPU hardware in addition to standard CPUs (as standard Go programs).
+
+## Goal pages
+
diff --git a/docs/content/gosl.md b/docs/content/gosl.md
diff --git a/goal/GPU.md → docs/content/gpu.md b/goal/GPU.md → docs/content/gpu.md
@@ -1,12 +1,20 @@
-# Goal GPU support
++++
+Categories = ["Gosl"]
+Title = "GPU"
+Name = "GPU"
++++
 
-The use of massively parallel _Graphical Processsing Unit_ (_GPU_) hardware has revolutionized machine learning and other fields, producing many factors of speedup relative to traditional _CPU_ (_Central Processing Unit_) computation. However, there are numerous challenges for supporting GPU-based computation, relative to the more flexible CPU coding.
+The use of massively parallel _Graphical Processsing Unit_ (**GPU**) hardware has revolutionized machine learning and other fields, producing many factors of speedup relative to traditional _CPU_ (_Central Processing Unit_) computation. However, there are numerous challenges for supporting GPU-based computation, relative to the more flexible CPU coding.
 
-The Goal framework provides a solution to these challenges that enables the same Go-based code to work efficiently and reasonably naturally on both the GPU and CPU (i.e., standard Go execution), via the [gosl](../gosl) package. Debugging code on the GPU is notoriously difficult because the usual tools are not directly available (not even print statements), so the ability to run exactly the same code on the CPU is invaluable, in addition to the benefits in portability across platforms without GPU hardware.
+The [[Gosl]] Go shader language operating within the broader [[Goal]] augmented version of the Go lanuage provides a solution to these challenges that enables the same Go-based code to work efficiently and reasonably naturally on both the GPU and CPU (i.e., standard Go execution).
 
-See the [gosl](../gosl) documentation for the details on how to write code that works on the GPU. The remainder of this document provides an overview of the overall approach in relation to other related tools.
+Debugging code on the GPU is notoriously difficult because the usual tools are not directly available (not even print statements), so the ability to run exactly the same code on the CPU and GPU is invaluable, in addition to the benefits in portability across platforms without GPU hardware.
 
-The two most important challenges are:
+See the [[gosl]] documentation for the details on how to write code that works on the GPU. The remainder of this document provides an overview of the overall approach in relation to other related tools.
+
+## Challenges for GPU computation
+
+The two most important challenges for GPU-based programs are:
 
 * The GPU _has its own separate memory space_ that needs to be synchronized explicitly and bidirectionally with the standard CPU memory (this is true programmatically even if at a hardware level there is shared memory).
 
@@ -24,20 +32,21 @@ The [JAX](https://github.com/jax-ml/jax) framework in Python provides one soluti
 
 We take a different approach, which is much simpler implementationally but requires a bit more work from the developer, which is to provide tools that allow _you_ to organize your computation into kernel-sized chunks according to your knowledge of the problem, and transparently turn that code into the final CPU and GPU programs.
 
-In many cases, a human programmer can most likely out-perform the automatic compilation process, by knowing the full scope of what needs to be computed, and figuring out how to package it most efficiently per the above constraints. In the end, you get maximum efficiency and complete transparency about exactly what is being computed, perhaps with fewer "gotcha" bugs arising from all the magic happening under the hood, but again it may take a bit more work to get there.
+In many cases, a human programmer can most likely out-perform the automatic compilation process, by knowing the full scope of what needs to be computed, and figuring out how to package it most efficiently per the above constraints. In the end, you get maximum efficiency and complete transparency about exactly what is being computed, perhaps with fewer "gotcha" bugs arising from all the magic happening under the hood, but it may take a bit more work to get there.
 
-The role of Goal is to allow you to express the full computation in the clear, simple, Go language, using intuitive data structures that minimize the need for additional boilerplate to run efficiently on CPU and GPU. This ability to write a single codebase that runs efficiently on CPU and GPU is similar to the [SYCL](https://en.wikipedia.org/wiki/SYCL) framework (and several others discussed on that wikipedia page), which builds on [OpenCL](https://en.wikipedia.org/wiki/OpenCL), both of which are based on the C / C++ programming language.
+The role of [[Gosl]] and [[Goal]] is to allow you to express the full computation in the clear, simple, Go language, using intuitive data structures that minimize the need for additional boilerplate to run efficiently on CPU and GPU. This ability to write a single codebase that runs efficiently on CPU and GPU is similar to the [SYCL](https://en.wikipedia.org/wiki/SYCL) framework (and several others discussed on that wikipedia page), which builds on [OpenCL](https://en.wikipedia.org/wiki/OpenCL), both of which are based on the C / C++ programming language.
 
-In addition to the critical differences between Go and C++ as languages, Goal targets only one hardware platform: WebGPU (via our [gpu](../gpu) package), so it is more specifically optimized for this use-case. Furthermore, SYCL and other approaches require you to write GPU-like code that can also run on the CPU (with lots of explicit fine-grained memory and compute management), whereas Goal provides a more natural CPU-like programming model, while imposing some stronger constraints that encourage more efficient implementations.
+In addition to the critical differences between Go and C++ as languages, Gosl targets only one hardware platform: WebGPU (via the [core gpu](https://github.com/cogentcore/core/tree/main/gpu) package), so it is more specifically optimized for this use-case. Furthermore, SYCL and other approaches require you to write GPU-like code that can also run on the CPU (with lots of explicit fine-grained memory and compute management), whereas Goal provides a more natural CPU-like programming model, while imposing some stronger constraints that encourage more efficient implementations.
 
 The bottom line is that the fantasy of being able to write CPU-native code and have it magically "just work" on the GPU with high levels of efficiency is just that: a fantasy. The reality is that code must be specifically structured and organized to work efficiently on the GPU. Goal just makes this process relatively clean and efficient and easy to read, with a minimum of extra boilerplate. The resulting code should be easily understood by anyone familiar with the Go language, even if that isn't the way you would have written it in the first place. The reward is that you can get highly efficient results with significant GPU-accelerated speedups that works on _any platform_, including the web and mobile phones, all with a single easy-to-read codebase.
 
-# Kernel functions
+## Kernel functions
 
 First, we assume the scope is a single Go package that implements a set of computations on some number of associated data representations. The package will likely contain a lot of CPU-only Go code that manages all the surrounding infrastructure for the computations, in terms of creating and configuring the data in memory, visualization, i/o, etc.
 
 The GPU-specific computation is organized into some (hopefully small) number of **kernel** functions, that are conceptually called using a **parallel for loop**, e.g., something like this:
-```Go
+
+```go
 for i := range parallel(data) {
     Compute(i)
 }
@@ -49,11 +58,11 @@ We assume that multiple kernels will in general be required, and that there is l
 
 Even though the GPU kernels must each be compiled separately into a single distinct WGSL _shader_ file that is run under WebGPU, they can `import` a shared codebase of files, and thus replicate the same overall shared code structure as the CPU versions.
 
-The GPU code can only handle a highly restricted _subset_ of Go code, with data structures having strict alignment requirements, and no `string` or other composite variable-length data structures (maps, slices etc). Thus, the [gosl](../gosl) package recognizes `//gosl:start` and `//gosl:end` comment directives surrounding the GPU-safe (and relevant) portions of the overall code. Any `.go` or `.goal` file can contribute GPU relevant code, including in other packages, and the gosl system automatically builds a shadow package-based set of `.wgsl` files accordingly.
+The GPU code can only handle a highly restricted _subset_ of Go code, with data structures having strict alignment requirements, and no `string` or other composite variable-length data structures (maps, slices etc). Thus, [[Gosl]] recognizes `//gosl:start` and `//gosl:end` comment directives surrounding the GPU-safe (and relevant) portions of the overall code. Any `.go` or `.goal` file can contribute GPU relevant code, including in other packages, and the gosl system automatically builds a shadow package-based set of `.wgsl` files accordingly.
 
 > Each kernel function is marked with a `//gosl:kernel` directive, and the name of the function is used to create the name of the GPU shader file.
 
-```Go
+```go
 // Compute does the main computation.
 func Compute(i uint32) { //gosl:kernel
 	Params[0].IntegFromRaw(&Data[i])
@@ -68,7 +77,7 @@ Perhaps the strongest constraints for GPU programming stem from the need to orga
 
 Thus, names must be chosen appropriately for these variables, given their global scope within the Go package. The specific _values_ for these variables can be dynamically set in an easy way, but the variables themselves are global.
 
-Within the [gpu](../gpu) framework, each `ComputeSystem` defines a specific organization of such GPU buffer variables, and maximum efficiency is achieved by minimizing the number of such compute systems, and associated memory buffers. Each system also encapsulates the associated kernel shaders that operate on the associated memory data, so
+Within the [core gpu](https://github.com/cogentcore/core/tree/main/gpu) framework, each `ComputeSystem` defines a specific organization of such GPU buffer variables, and maximum efficiency is achieved by minimizing the number of such compute systems, and associated memory buffers. Each system also encapsulates the associated kernel shaders that operate on the associated memory data, so
 
 > Kernels and variables both must be defined within a specific system context.
 
@@ -104,21 +113,10 @@ Furthermore:
 
 > Pointer-based access of global variables is not supported in GPU mode.
 
-You have to use _indexes_ into arrays exclusively. Thus, some of the data structures you may need to copy up to the GPU include index variables that determine how to access other variables. TODO: do we need helpers for any of this?
-
-# Examples
+You have to use _indexes_ into arrays exclusively. Thus, some of the data structures you may need to copy up to the GPU include index variables that determine how to access other variables.
 
-A large and complex biologically-based neural network simulation framework called [axon](https://github.com/emer/axon) has been implemented using `gosl`, allowing 1000's of lines of equations and data structures to run through standard Go on the CPU, and accelerated significantly on the GPU.  This allows efficient debugging and unit testing of the code in Go, whereas debugging on the GPU is notoriously difficult.
+## Examples
 
-# TODO
-
-## Optimization
-
-can run naga on wgsl code to get wgsl code out, but it doesn't seem to do much dead code elimination: https://github.com/gfx-rs/wgpu/tree/trunk/naga
-
-```
-naga --compact gpu_applyext.wgsl tmp.wgsl
-```
+A large and complex biologically-based neural network simulation framework called [axon](https://github.com/emer/axon) has been implemented using `gosl`, allowing 1000's of lines of equations and data structures to run through standard Go on the CPU, and accelerated significantly on the GPU. This allows efficient debugging and unit testing of the code in Go, whereas debugging on the GPU is notoriously difficult.
 
-https://github.com/LucentFlux/wgsl-minifier does radical minification but the result is unreadable so we don't know if it is doing dead code elimination.  in theory it is just calling naga --compact for that.
 
diff --git a/docs/content/histogram.md b/docs/content/histogram.md
@@ -0,0 +1,6 @@
++++
+Categories = ["Stats"]
++++
+
+**Histogram** computes histograms. Go docs: [[doc:stats/histogram]]
+
diff --git a/docs/content/home.md b/docs/content/home.md
@@ -11,12 +11,14 @@ Cogent Lab is still under development, but the basic API should be somewhat stab
 
 Features include:
 
-* The [[goal]] language transpiler (generates standard Go code) that supports more concise math and matrix expressions that are largely compatible with the widely used numpy framework, in addition to shell command syntax, so it can be used as a replacement for a command-line shell.
+* The [[Goal]] language transpiler (generates standard Go code) that supports more concise [[math]], [[matrix]], and [[stats]] expressions that are largely compatible with the widely used [NumPy](https://numpy.org/doc/stable/index.html) framework, in addition to [[shell]] command syntax, so it can be used as a replacement for a command-line shell.
 
-* A [[tensor]] representation for n-dimensional data, which serves as the universal data type within the Lab framework. The [[table]] uses tensors as columns for tabular, heterogenous data (similar to the widely-used pandas data table), and the [[tensorfs]] is a hierarchical filesystem for tensor data that serves as the shared data workspace.
+    + The [[Gosl]] (_Go shader language_) that allows you to write Go (and [[Goal]]) functions that run on either the CPU or the [[GPU]], using the WebGPU framework that supports full GPU compute functionality in the web browser and on desktop platforms.
+
+* A [[tensor]] representation for n-dimensional data, which serves as the universal data type within the Lab framework. The [[table]] uses tensors as columns for tabular, heterogenous data (similar to the widely-used [pandas](https://pandas.pydata.org/) data table), and the [[tensorfs]] is a hierarchical filesystem for tensor data that serves as the shared data workspace.
 
 * Interactive, full-featured [[plot]]s and other GUI visualization tools.
 
-* The overarching `lab` API for flexibly connecting data and visualization components, providing the foundation for interactive data analysis applications integrating different Cogent Lab elements.
+* The [[lab]] user interface API for flexibly connecting data and visualization components, providing the foundation for interactive data analysis applications integrating different Cogent Lab elements.
+
 
-* The [[gosl]] (Go shader language) that allows you to write Go (and [[goal]]) functions that run on either the CPU or the GPU, using the WebGPU framework that supports full GPU compute functionality through the web browser.
diff --git a/docs/content/lab.md b/docs/content/lab.md
@@ -0,0 +1,11 @@
+
+**Lab** contains graphical interface elements for Cogent Lab (Go docs: [[doc:lab]]), including:
+
+* [[Browser]] is a default combination of the following elements.
+
+* [[Tabs]] provides functions for creating tabs with data elements such as [[plot]]s and views of [[table]]s.
+
+* [[DataTree]] provides a tree-structured view of [[tensorfs]] and regular filesystem data.
+
+## Lab pages
+