(diagram)=
# Diagram View

The topology of a xronos program can be visualized in an interactive diagram using our VS Code extension.

## System Requirements

- A Linux-based operating system. We recommend [Ubuntu](https://ubuntu.com/download/desktop) 22.04 or newer.
- `node.js` needs to be installed. We recommend version `23.1.0`, and versions
  older than `16.0.0` will not work. We recommend using `nvm` to manage your
  `node` version, as described
  [here](https://github.com/nvm-sh/nvm/blob/master/README.md).
- VS Code needs to be installed. On Ubuntu, download the package matching your
  architecture ([x86_64](https://code.visualstudio.com/docs/?dv=linux64_deb),
  [aarch64](https://code.visualstudio.com/docs/?dv=linuxarm64_deb)) and install
  the downloaded file using `dpkg -i <downloaded_file>`.

## Installation

Start VS Code and open the market place using {menuselection}`View -->
Extensions`. Type "Xronos" into the search field and then click the
{guilabel}`Install` button next to the Xronos extension.

(rendering_diagrams)=
## Rendering Diagrams

Open VS Code and bring up the Command Palette using
{kbd}`Ctrl`+{kbd}`Shift`+{kbd}`P`. Type `Xronos: Diagram` and select the
corresponding entry using {kbd}`⏎`. This will open the Xronos Diagram view as
shown below.

![empty diagram](./_img/empty_diagram_vscode.png)

Initially, no diagram is shown. The diagram view automatically renders the
program that was last executed. Try running the {ref}`hello_world` example. If
you like, you can use the builtin terminal of VS Code.
```console
$ source .venv/bin/activate
$ python hello.py
```

Now the diagram view updates and shows the `hello` reactor that we just executed.
![hello diagram](./_img/diagram_hello_vscode.png)

You may run arbitrary xronos programs and observe their topology in the diagram
view. For instance, the {ref}`YOLO<yolo>` example is rendered as shown below.
![YOLO diagram](./tutorials/_img/diagram_yolo.png)

## Code Navigation

You can also use the diagram to navigate your code. Select an element in the
diagram and press {kbd}`F12`, or click on an element while holding down the
{kbd}`Ctrl` key ({kbd}`Cmd`/{kbd}`⌘` key on Mac). This will bring you to the
location in the Python code that created the element.

(viewing_diagram_server_logs)=
## Viewing Diagram Server Logs

To view the diagram server logs, open the VS Code integrated terminal using
{kbd}`Ctrl`+{kbd}``​`​`` and navigate to the terminal titled `Xronos Diagram
Server`.

## Interoperability with `WSL` or `Visual Studio Code Remote - SSH`

We recommend Microsoft's `WSL` or `Visual Studio Code Remote - SSH` extensions
for users who prefer to use an unsupported operating system or who are doing
on-target development on a headless machine.

The diagram viewer requires port forwarding in order to work with the `Visual
Studio Code Remote - SSH` extension. `WSL` does not require port forwarding.

The first time you start a new VS Code session using the `Visual Studio Code
Remote - SSH` extension and [open the diagram viewer](rendering_diagrams), you
may receive a notification like the following:

![Port forwarding notification](./_img/notification_port_forwarding.png)

If you do not receive this notification, it could be because automatic port
forwarding is not enabled in your VS Code settings. Therefore, you will need to
forward a port manually by following the directions in [VS Code's official
documentation](https://code.visualstudio.com/docs/editor/port-forwarding) or by
executing the command `VS Code: Forward a Port` in the VS Code command palette.
The port you will need to forward will be specified in the
[logs](viewing_diagram_server_logs) as some port number between 3001 and 3020.