App Structure

In this section, we'll explore how a Compute application is structured in code and how each of its sections is rendered on the platform.

We'll use the training_boilerplate.py app code you've created in the Quick Start Guide section to explain the different components.

App Metadata

The App Metadata defines some information that gives a summary of the app for other users. This data is composed by two files:

• App Meta
• Readme

App Meta app_meta.yaml

Use app_meta.yaml to set the metadata of your app. The following fields can be set:

• app_title: Name of the app

• discipline: Discipline of the app. The different disciplines can be seen here

• subcategory (Optional): Subcategory List of sub-categories (default=[])

• app_status (Optional): App Status Check the different options here (default=InProgress)
• authors (Optional): Authors of the app (default=[])
• reviewers (Optional): Reviewers of the app (default=[])
• is_multi_stage (Optional) Is Multi Stage must be set to True when using multi-stage apps (default=False)

Example:

app_title: My First App
discipline: Training
subcategory:
  - Generic
app_status: Verified
reviewers:
  - John Doe
authors:
  - John Doe
is_multi_stage: false

App Readme README.md

Use this file to add a description to your app. The content will then be rendered nicely in markdown.

The app's meta will be rendered in the App Details section of the app's page:

App Building Class AppStageCompute

The AppStageCompute class provides all the methods required to render your application on the Compute platform.

To build an app, you need to create a new class that inherits from AppStageCompute. For example:

class TrainingBoilerplate(AppStageCompute):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

Class Naming

Note that within a single collection, each app must have a unique class name. For example, if you've downloaded a collection containing the class name TrainingBoilerplate, you cannot load another app with the same class name within that collection.

The AppStageCompute class exposes two distinct types of methods:

• Execution methods
• Content methods

Execution methods are the top-level methods executed when you open and run an app. They can contain calls to Content Methods, which are responsible for adding content to the app, such as inputs, calculations, tables, and plots.

Execution methods

Execution Methods handle the app's code execution in different states. For instance, when you first load an app, only the register_parameters and build_parameters methods are executed. However, when you click the Compute button, all Execution Methods are run. We'll delve deeper into this process in App Execution Flow.

1. Adding Input Parameters

Adding input parameters involves two phases:

• Registering the input parameters using the register_parameters() method
• Exposing these inputs in the app using the build_parameters() method

1.1. Registering Input Parameters with register_parameters()

Define the input parameters used in the application, by calling the input_parameter method. This method adds a primitive (int, float or bool) type of input to the app.

Example:

def register_parameters(self):
    ...

    self.input_parameter(var_name="width",
                         description="This is where a more verbose description can be given.",
                         fullname="Width of rectangle",
                         unit="mm",
                         bind_ui=UiNumberInput(min_val=10, max_val=1000, step=1.0, default=100))

Importance of the var_name argument

The var_name is crucial as it serves as a reference to the input's value in calculations and other parts of the app.

Other Input types

For more complex data types, such as tables or files, refer to the API Reference and look for methods starting with input.

At this stage, if you render your app, the input parameter will only be registered and not displayed.

This registration process is essential for providing users with a list of input arguments on the platform. To view this list, navigate to the App Details section of the app page and click the Parameters button:

Note

This is particularly important if an app is to be reused within other apps. Currently, this feature is only available for deployed apps.

1.2. Exposing Input Parameters on the User Input section with build_parameters()

To display the input parameters, use the expose_parameter method within the build_parameters() execution method:

Example:

def build_parameters(self):
    ...

    self.expose_parameter("width")

Expose All Parameters

To expose all registered parameters at once, use the expose_all_parameters() method.

Once exposed, the input will appear in the User Input section with the chosen UI element and in the Detailed Output section:

2. Building the Detailed Output section with build_report()

Within the build_report() method define your app's calculations, including equations and plots. Use the add_calc() method to add calculations based on other parameters in your application.

Example:

def build_report(self):
    ...

    self.add_calc(
        var_name='ArbitraryResult',
        fullname='200 Multiplied by the "width value"',
        unit='mm',
        equation='{width} * 200'
    )

To execute the app's calculations defined in the build_report() method, click the Compute button on the app's page. The results will appear in the Detailed Output section:

If the computation is successful, the ring on the Compute button will turn from orange to blue. You can also expand the calculations in the Detailed Output panel to see the equation rendered in mathematical format.

3. Building the Summary Section build_summary()

This optional execution method allows you to add a summary section to the app's page. Use the ref_to_summary() method to reference important calculations, tables, or plots.

Example:

def build_summary(self):
    ...

    self.ref_to_summary("ArbitraryResult")

The ArbitraryResult parameter will now be displayed in the Summary Output section of the app's page:

Content methods

These are the methods that add content to the app, such as input parameters, calculations, plots, tables, and many others.

We've covered some of the available content methods, such as input_parameter(), expose_parameter(), add_calc(), and ref_to_summary(). For more information about all other methods, please refer to the API Reference