Interactive Aner notebooks

Aner notebooks use .anernb (Interactive Aner Notebook) for the document and .aner for plain source. The current editor extension (0.1.16) provides Markdown, image attachments, highlighted Aner code, saved outputs, and two document execution modes:

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. Reports are text summaries; the current notebook editor does not provide a live topology panel, loss chart, variable explorer, or model checkpoint format. Editing a configuration cell does not automatically invalidate a fitted variable or saved output: rerun fitting and evaluation explicitly. Restart followed by Run All gives a clean experiment from the notebook source.

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 require explicit checked .unwrap() before use.

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, and outputs, not live variables or a model checkpoint. Reopening a notebook can show historical outputs while its new session has no variables. Editing code, moving cells, or changing data does not automatically mark saved output stale. Restart and run the required cells in order when checking that the notebook is reproducible.

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.

Existing viz.capture calls still need the CLI debug report option to produce offline training reports. Neither execution mode supplies that option or automatically embeds the reports. Use the terminal workflow in visual debugging.

Other editors and planned tools

The current notebook workflow is VS Code with the Aner extension. A Jupyter kernel and JupyterLab file integration are future work. Although .anernb stores familiar notebook content in nbformat JSON, it cannot currently be opened and executed as an Aner notebook in JupyterLab.

A variable explorer, live network diagrams, training charts, pause/step debugging, automatic provenance capture, and stale output indicators are proposed features. They are not available in the current extension. See the notebook inspection proposal for the planned direction. For now, use module summaries, explicit prints, and the existing offline visual reports to inspect an experiment.