Interactive Aner notebooks

Aner notebooks use .anernb (Interactive Aner Notebook) for the document and .aner for plain source. The current editor extension (0.1.28) provides Markdown, image attachments, highlighted Aner code, saved outputs, an offline training report viewer beside the notebook, and two document execution modes. Development/production is a separate runtime setting; production is the default:

Aner — notebook follows the execution mode saved in the document. New notebooks use shared variables. Aner executes each cell directly in its native runtime. Persistent sessions retain values and definitions between cells.

Open and run

Install a compatible Aner executable for your operating system and the VS Code extension supplied with the same release, when available. See installation and release availability and Aner in VS Code. The setup uses installed binaries; no language source checkout is needed.

1. Open your own project folder in VS Code. To use the supplied examples, open the folder that contains their examples/ directory.
2. Open variables across cells, or use Aner: New Notebook in the Command Palette.
3. If the file appears as JSON, choose Reopen Editor With… → Aner Notebook from its editor tab's context menu.
4. Save a new notebook as a .anernb file inside your project, then run its code cells in order or choose Run All. If prompted for a kernel, choose Aner — notebook.

After updating the extension, run Developer: Reload Window. The cell status shows the effective execution mode. Reloading clears live notebook state, so rerun the defining cells before using their variables.

For a notebook containing full main programs, run Aner: Use Independent Programs. The Iris neural classifier and hello notebook already specify independent mode in their metadata. Use Aner: Use Shared Variables, or an independent cell’s Use shared variables status action, to change a notebook to shared state. Save the document to persist a mode change. Changing mode cancels old work and clears session state; neither command executes or replays cells. Rerun from the first defining cell afterward. The mode applies to the whole notebook and is not inferred from cell source.

Add Aner code cells for calculations and Markdown cells for explanations or images. The active light or dark theme controls Aner syntax colors. Execution requires a trusted workspace; viewing and editing remain available without trust. The extension invokes your installed Aner executable.

Concise neural network notebook

Open the concise Iris notebook from an installed release that includes this example and its matching editor extension. It contains separate cells for imports and splitting, network topology, fitting, and held out evaluation. Choose Run All. The notebook explicitly uses shared variable mode; no function wrapper or controller switch is needed.

Named arguments and typed methods keep each cell short: flowers.split(test: 0.2, seed: 2026), network.dense(inputs: 4, outputs: 8), and pipeline.fit(split.train(), epochs: 2000, rate: 0.1). A leading . continues a chain across lines. fit returns a fresh fitted snapshot, learns the standardizer only from training rows, and does not change the configuration or a previous fitted result. Evaluating test rows reuses the fitted statistics. See the neural API and limits.

The document starts with empty outputs and preserves Iris attribution. Production returns text results; Development additionally supplies bounded variable/object observations and captured loss after each completed cell. Open the development Iris notebook for custom initialization and warm start cells. Use Inspector and Aner: Open Development Training Report for its recorded state. Fitted models can be saved and loaded separately; saved notebook output itself is not a checkpoint. Editing a configuration does not retrain a retained model: rerun fitting and evaluation explicitly. Restart followed by Run All gives a clean experiment. Streaming during execution and pause/step debugging remain future work.

Development and production controls

Choose Dev in the notebook toolbar to record observations and Prod to disable them. This choice is independent of Shared variables versus Independent programs. Changing runtime mode cancels queued/active work and clears the session; rerun setup cells. Choosing the already active mode retains the current state. Save the notebook to retain metadata.aner.runtime_mode: "development"; missing metadata selects production.

Inspector displays typed globals, bounded collection/object trees and reference diagrams, named captures, and per fit loss after execution completes. Int64 values retain exact decimal text. Set aner.notebook.developmentValues to opt into bounded raw tensor/neuron values; it defaults to false. Source edits mark observations stale, and restart, Stop, timeout, runtime failure, or mode changes invalidate live inspection state. Static errors preserve earlier variables; failure observations are labeled historical.

Aner: Open Development Training Report opens the captured native tensor topology, activations, and available gradients from a completed training cell. A later cell may retain that training view as historical, with the originating execution number, while the variable table represents the current completed cell. Inspection does not evaluate user expressions, edit variables, rewind training, or pause execution.

See the mode guide for limits, linked list observations, neural configuration, checkpoints, and performance. Use the linked list development notebook to inspect append, prepend, and removal across cells.

Open a recorded training report

Version 0.1.17 added Open training report to the notebook toolbar and code cell status bar. The Command Palette equivalent is Aner: Open Training Report. It opens an existing report beside the notebook without running cells or generating a report.

First generate a report in the terminal from the corresponding source program, using a new output directory. For the detailed Iris example, run from the folder containing examples/:

aner run examples/neural_iris.aner --debug-viz reports/iris-notebook --debug-values

With neural_iris.anernb active, click Open training report and select either reports/iris-notebook/index.html or reports/iris-notebook/trace.json. Keep both files in the same directory. The viewer displays recorded network states, the loss chart, and available values and gradients. Use the captured step slider or a loss chart point to select a snapshot; select a neuron and batch row to inspect recorded values.

The extension remembers the selected report for that notebook in the current workspace. Later Open training report actions reuse it; Aner: Choose Training Report selects a different report. This association is workspace state and is not saved inside the notebook or included when sharing it.

These are historical captures from the selected report. Opening it does not connect to the notebook session, track training, or verify that its source matches the notebook. Editing either source does not update or mark the report stale. Generate a fresh report in another new directory and choose it when you need observations from changed code. See visual training reports for capture limits and controls.

Object oriented structures notebook

Open objects and data structures with the matching installed Aner executable and editor extension. Run All defines and exercises a linked list, a cyclic graph, and a binary search tree in shared state. The tree is not a multiway B tree.

Run class definition cells once per session. Class definitions cannot be replaced while live objects may refer to them. To edit or rerun those definitions, choose Aner: Restart Notebook Session, then Run All. Demonstration cells can reuse the checked definitions. Objects use reference identity: aliases observe writes to declared mutable fields. Nullable links allow direct use after a null check proves they are nonnull; .unwrap() remains available for unguarded extraction.

After a successful cell, Aner traces live global object references and reclaims unreachable objects, including cycles. Collection does not run during a cell; object/field allocation ceilings still apply. Runtime errors, including unwrapping null, clear the session. Saving source and outputs does not save the object heap. See the OOP guide for the limits and semantics.

Private state and generic classes

Open the generic linked list notebook with the matching installed Aner executable and editor extension. Four code cells define Node/LinkedList/Employee, use numeric lists, store Employee references, and construct nested generic nodes. Use Run All after a fresh session.

Fields are private by default; methods are public by default, with explicit public/private available for both. The synthesized constructor accepts initial values for all fields, including private ones. The examples access state through methods. Node<Int64> and LinkedList<Employee> require explicit type arguments and retain static typing; Int32 is not implemented. The structure examples mark fields accessed externally as public.

Class templates and concrete specializations persist with notebook objects. Restart before redefining templates or rerunning the definition cell. Static errors preserve prior state and roll back new specializations; runtime errors clear the session. Generic expansion and object allocations have separate limits; see the OOP guide. No checkpoint or live object serialization is implied by saved output.

Concise object methods

Open concise methods with the matching installed Aner executable and editor extension. Four code cells define Cell<T>, construct and update a value, demonstrate a local variable shadowing a field, and reset by calling another method implicitly. The output groups are 10, 25, then 0, 25, then 0.

The getter is fn get() { return value }; the setter keeps its input type and uses self.value = value to distinguish the field from its parameter. Aner infers result types statically; explicit self and result annotations remain valid. Value return inference cycles still need annotations. Run the definition cell once per session, or restart before Run All. The structures and generics notebooks also use concise methods.

Variables without a function

Run this first cell in shared variable mode:

var a = 10
let b = 20
c = 30

Then run a second cell:

a = a + 5
a + b + c

The second cell displays 65. No fn main is needed. var creates a mutable binding, let creates an immutable binding, and a bare assignment creates a mutable binding when the name is not already visible. For an existing name, assignment updates its value and must respect its type and mutability. Thus b = 25 is an error because b was declared with let.

Aner infers Int64 for these integer literals. The type remains fixed: a = 2.5 is an error rather than silently changing a to Float64. Use a different name for a different type. Explicit annotations such as var a: Int64 = 10 are also available.

At the outermost level of a persistent session cell, a scalar expression such as a or a + b displays its result. print(a) also works. This automatic display does not apply inside function bodies, nested blocks, or standalone .aner programs. Composite values such as tensors and datasets still need their module accessors or summaries.

Semicolons are optional at a line break, the end of the source, or a closing brace. A continuing expression can span lines: 1 + followed by 2, or a multiline function call, remains one expression. An operator at the start of the next line can also continue the previous expression; use an explicit semicolon when that boundary must end the statement. Separate multiple simple statements on the same line with semicolons. A bare return at a line break returns Unit and is only valid inside a function.

What persists and how to restart

Each open notebook has its own native session process, created on its first persistent execution. Cells execute against the current state in the order you run them. Imports, typed global bindings, datasets, tensors, gradient state, user functions, class definitions, and object references can carry between cells. Defining a function does not require a main function. Imports must precede functions and executable statements within each cell; an import used in an earlier successful cell remains available.

Rerunning an explicit top level declaration such as var a = 10 or let b = 20 reinitializes that binding if its type and mutability match the previous declaration. This supports rerunning setup cells; it does not make a later assignment to let legal. Duplicate declarations within one cell remain errors. Function and class redefinition are not supported: restart before rerunning or changing a cell that defines either.

The entire cell is parsed and statically checked before any statement executes. A syntax or type error preserves the existing session state. An error during execution clears the entire session, including previously successful cells' values, functions, and imports. Earlier output or other external effects are not rolled back. After such an error, rerun the cells that establish the state you need.

Use Aner: Restart Notebook Session in the Command Palette to clear the current notebook's state. Stop, an execution timeout, notebook closure, or extension reload also ends its process and releases its values. Stopping is cancellation, not a pause that can resume later. The next user execution starts a fresh session; it does not restore or replay earlier cells. A failure stops the remaining cells in the same execution request.

Saving the notebook stores source, document content, runtime mode metadata, and outputs, not live variables or a model checkpoint. Use fitted.save(path) and ml.load_classifier(path) for an explicit neural model checkpoint. Reopening a notebook can show historical outputs while its new session has no variables. Development inspection marks source edits stale and tracks the completed cell identity. Ordinary saved text outputs are historical content; changed external data is not automatically tracked. Restart and run the required cells in order when checking that the notebook is reproducible.

Data structures across cells

Built in data structure values and their aliases persist between successful cells in a shared session. Runtime failures clear session state; static failures preserve previous cells. Development observations retain bounded values and object identities after each completed cell.

The collection notebook demonstrates interactions between values across cells. Its examples are a tutorial; declaration, method, error, and complexity contracts are defined separately in the Array, Dictionary, DynamicArray, List, NDArray, Set, and Tensor references.

Installed executable and working directory

If the installed aner command is available on VS Code's PATH, the extension can use it. For a specific installation, set Aner › Notebook: Executable (aner.notebook.executable) to the full path of your installed aner binary, or aner.exe on Windows. That explicit setting takes priority. See executable setup in VS Code for examples and troubleshooting.

The working directory is the notebook's containing workspace folder, or its saved directory when outside a workspace. Relative CSV paths use that directory. For supplied examples, open the folder containing examples/ so paths such as examples/fixtures/visits.csv resolve correctly. Save a new notebook before executing it.

The same VSIX can be installed on macOS, Windows, or Linux; each machine needs a native Aner executable built for its own operating system and architecture. Check release availability and installation before choosing a package. Install the binary and extension versions recommended together by that release. Updating the VSIX alone does not update an older executable or copy the new example files.

Persistent notebooks require a release with native session support. The extension handles the session connection; you do not need to start a separate kernel service. Notebook execution uses the installed Aner executable and the compatible VS Code extension.

Execution limits and diagnostics

Output limit failures clear session state. Aner's existing call depth, tensor, graph, and data operation bounds also apply. These limits are not a process memory quota; several retained values can consume more memory than any one operation's budget. Restart or close the notebook to release its session.

The editor records execution order and shows stdout and diagnostics beneath the cell after execution completes. A runtime error inside a function retained from an earlier cell uses that function's stored source in its diagnostic. Complete program mode writes a unique temporary .aner file, removes it after execution, and may name it in diagnostics. Persistent mode sends the original source through the native framed protocol without generating wrapper code.

Document content and storage

The document uses nbformat 4.5 JSON. The serializer preserves cell IDs, metadata, Markdown, raw cells, attachments, execution counts, and supported outputs through open/save operations. Raw cells remain document content and are not executed. The .anernb suffix selects Aner's notebook editor; it does not make an arbitrary JSON file executable.

Authored diagrams are separate from computed observations. The Iris topology image explains a 4 → 8 → 3 network; it does not display captured activations or weights. Image attachments do not become Aner language syntax. The renderer displays supported attachments in image contexts, preserving their source content in the document.

Examples are distributed with empty saved outputs and no execution counts. The Iris notebook embeds its complete .aner program; the variables notebook demonstrates shared state. Editing a notebook does not change its corresponding .aner file. The Iris example retains source citations and CC BY 4.0 attribution; see the Iris notices. Its teaching result is not a general benchmark.

Development mode enables native neural observations, including explicit viz.capture calls, and makes their completed cell training view available automatically. Production disables recording. The separate Open training report workflow still accepts historical CLI reports generated through the terminal workflow; opening that report does not associate its source with the live session.

Other editors and planned tools

The optional Aner Jupyter integration executes .ipynb notebooks through the native session engine. Select the Aner kernel in a configured notebook application and open the development example.

Use %aner dev, %aner dev values, %aner prod, %aner variables, or %aner reset in separate control cells. Jupyter provides read only variable/object views, per fit loss, and an operation topology summary after cells complete. Mode changes/reset clear state. Full recorded neuron/dependency/gradient controls remain available in the standalone report. .anernb remains the VS Code document suffix; a custom JupyterLab .anernb file editor and automatic import/export remain future work.

Streaming charts while a cell runs, pause/step debugging, source/data dependency analysis, and a general model/data explorer remain future work. See inspection status and remaining work.

Shaped arrays across cells

The multidimensional notebook uses built in NDArray, shared fixed reshape, detached transpose/flatten, broadcasting and matrix products. Dev Inspector reports dtype, dimensions, element strides and stable storage IDs. Views survive successful cell boundary collection through their own buffer ownership. Runtime shape/numerical/quota errors still clear the session, while static dtype failures preserve previous cells. Read multidimensional contracts and complexity.

Neural research example

The research notebook uses explicit CPU placement, He/Xavier initialization, Adam, measured fixed epoch progress, and a genuine warm start. Extension 0.1.28 shows Tensor placement and measured timing in Inspector after each completed cell. The same workflow in Jupyter uses the optional Aner kernel. Progress is buffered until a notebook cell returns; live notebook streaming remains future work. See the neural workflow for full API and hardware limits.

Notebook cells default to a 120 second timeout. Set aner.notebook.timeoutMs to an integer from 1 through 86,400,000 before a longer run; 600000 permits ten minutes. Changing the resource setting preserves session state and affects subsequent cells. An active request retains its original deadline; timeout still terminates the process and clears variables. See the editor guide.