Merge branch 'meeting_feedback' into 'main'

![](fig/Nova_Architecture.png)

In essence, you will build your **User Application** using the **NOVA Libraries**, which in turn will interact with the **NDIP Platform** to perform neutron data analysis tasks. NOVA applications do not require a GUI to leverage NDIP. We'll demonstrate this in Episode 3, where we\'ll use 'nova-galaxy' to create a simple python script which connects to NDIP and launches a tool. In episode 4, we\'ll extend that python script to include a simple GUI with the support of 'nova-trame' and 'nova-mvvm'.

In essence, you will build your **User Application** using the **NOVA Libraries**, which in turn will interact with the **NDIP Platform** to perform neutron data analysis tasks. NOVA applications do not require a GUI to leverage NDIP. We\'ll demonstrate this in Episode 3, where we\'ll use 'nova-galaxy' to create a simple python script which connects to NDIP and launches a tool. In Episode 4, we\'ll extend that python script to include a simple GUI with the support of 'nova-trame' and 'nova-mvvm'.

## What Will You Learn?

## Install Project Dependencies

1.  **Clone the Template:**  Follow the instructions in the "Getting Started with a Template Application" episode to clone the NOVA template using `copier`.  This will create a new directory (e.g., `nova_tutorial`) containing your project files.

1.  **Clone the Template:**  Follow the instructions in the "Getting Started with a Template Application" section to clone the NOVA template using `copier`.  This will create a new directory (e.g., `nova_tutorial`) containing your project files.

2.  **Navigate to the Project Directory:**  Open your terminal and navigate to the newly created project directory:

    ```bash

# 3. Programming with NDIP

In this section, we will start using the `nova-galaxy` library to interact with the NDIP platform and run a neutron analysis tool.  First, ensure you have set your `GALAXY_URL` and `GALAXY_API_KEY` as environment variables, as explained in the notes at the end of this episode.  We also need to add `nova-galaxy` as a project dependency.

In this section, we will start using the `nova-galaxy` library to interact with the NDIP platform and run a neutron analysis tool.  First, ensure you have set your `GALAXY_URL` and `GALAXY_API_KEY` as environment variables, as explained in the Summary and Setup Episode.  We also need to add `nova-galaxy` as a project dependency.

:::::::::::::::::::::::::::::::::::::::  callout

From the command line, type `poetry add nova-galaxy@^0.7.0`. This command will add the nova-galaxy library to the pyproject.toml file as a project dependency. Then run `poetry install` to update your project dependencies.

::::::::::::::::::::::::::::::::::::::::::::::::::

## Interacting with NDIP via `nova-galaxy`

You should see `Fractal tool finished successfully.` printed to the console.

## Asynchronous tool execution

At times, it may be desirable to execute a tool or workflow without waiting on the result. The class Tool method run has an optional `wait` parameter. The default is true so that the tool is run in a blocking manner. However, by setting the parameter to false, the tool will be run asynchronously in a non-blocking manner.

```

            output = tool.run(data_store, params, wait=False)

```

Note, when run in this manner, output will be `None`. In order to retrieve results, you can use `tool.get_results()`. If the tool has not finished execution, this will also return `None`. As soon as results are available, the method will provide the results, exactly like the blocking execution.

## Tool output

Tool execution often results in some type of output. In the Fractal example, the tool output is a singular image file. A tool can have multiple outputs and sometimes these outputs are grouped together in a collection. In `nova-galaxy`, a singular file is called a Dataset and a group of files is called a DatasetCollection. The `Dataset` and `DatasetCollection` classes support the following methods:

If a tool run results in a `Dataset` or `DatasetCollection`, an `Output` is returned from the run method. `Output` is an encapsulation of the output datasets and collections from a Tool. A tool execution can result in multiple `Dataset` and `DatasetCollection`, therefore, these are all grouped in the `Outputs` class for easier consumption.

In the Fractal example, the Tool.run comman returns an instance of the `Output` class which we save to the variable `output`. The Fractal tool [xml file](https://code.ornl.gov/ndip/galaxy-tools/-/blob/dev/tools/neutrons/test_tools/fractal.xml?ref_type=heads) defines that successful execution of the tool will result in a `Dataset` named `output`. This `Dataset` is then downloaded to the local file path `image.png`.

In the Fractal example, the Tool.run command returns an instance of the `Output` class which we save to the variable `output`. The Fractal tool [xml file](https://code.ornl.gov/ndip/galaxy-tools/-/blob/dev/tools/neutrons/test_tools/fractal.xml?ref_type=heads) defines that successful execution of the tool will result in a `Dataset` named `output`. This `Dataset` is then downloaded to the local file path `image.png`.

```python

    output = tool.run(data_store, params)

The Outputs can be used by the rest of your application, saved, or simply discarded. Outputs is also iterable, so you can use a for-loop to loop through all the contained datasets and collections. If your Datastore is persisted (using the persist() method), then a copy of the Datasets and DatasetCollections will reside on the NDIP platform, so it is not necessary to maintain a local copy.

## Asynchronous tool execution

At times, it may be desirable to execute a tool or workflow without waiting on the result. The class Tool method run has an optional `wait` parameter. The default is true so that the tool is run in a blocking manner. However, by setting the parameter to false, the tool will be run asynchronously in a non-blocking manner. It is beyond the scope of this episode, but if you were to attempt modify the example to run the tool asynchronously, your code might look something like this.

```python

            tool.run(data_store, params, wait=False)

    def check_for_output(self, tool):

        if(tool.get_results()):

            output.get_dataset("output").download("image.png")

```

Note, when run in this manner, the output of tool.run() will be `None`. In order to retrieve results, you can use `tool.get_results()`. If the tool has not finished execution, this will also return `None`. As soon as results are available, the method will provide the results, exactly like the blocking execution.

## Next Steps

In this section, you learned how to use the `nova-galaxy` library to run a tool on NDIP. In the next sections, we will expand on this to create a full user interface to make this functionality accessible to the end user.

Fortunately, the template application we used in this tutorial already includes a `Dockerfile` that you can use as a starting point. The Dockerfile is a set of instructions that Docker uses to build your container image.

Here\'s what the Dockerfile typically includes:

* **Base Image:** Specifies the base operating system and environment for your application.

* **Dependencies:** Describes how to install any required libraries or packages.

* **Application Files:** Defines how to copy your application code into the container.

* **Entrypoint:** Sets the command that is run when the container starts.

To containerize your application, you would:

1. Navigate to the top level of your project (where the `dockerfiles` folder is).

2. Run the docker build command in the following format `docker build -t <your_image_name>:<your_image_tag> -f dockerfiles/Dockerfile .`

3. Test your docker container using the command `docker run <your_image_name>:<your_image_tag>`.

Once your application is containerized, you will also need to define your tool using an XML file. This XML file describes your tool to the NDIP platform, including its inputs, outputs, parameters, and the Docker container image that should be used to run the tool. The NDIP platform makes use of the Galaxy tool framework.

The XML file includes:

*   **Tool ID:** A unique identifier for your tool.

*   **Name and Description:** User-friendly name and description of the tool.

*   **Inputs:** Defines the input parameters, including their types, labels, and optional constraints.

## Putting It All Together

Once you have your Docker container and tool XML file, you would:

1. Upload the Docker image to a container registry.

2. Upload the XML file to the NDIP platform.

3. Make sure that the API_KEY and GALAXY_URL are passed to the application as environmental variables.