Structure of the Insight Python Application File Template

The first lines in the file enable you to import the different packages required by the module, as well as any others you need for your application.

import pandas as pd
import xpress as xp
import xpressinsight as xi
import sys

Note: The Insight Python module uses the pandas library and reflects that data naming convention. The documentation for the pandas library can be accessed at https://pandas.pydata.org/.

The next section of code declares a Python class definition under the application name. Because this is a Python application, all code in this file follows that paradigm.

@xi.AppConfig(name="Quick Start with Python", version=xi.AppVersion(1, 0, 0))
class InsightApp(xi.AppBase):
    # Use type hints to declare the data model entities for the scenario.
    # Inputs need to be initialized in the load mode(s).
    # Entities are inputs if the manage attribute is xi.Manage.INPUT. This is the default, i.e., it can be omitted.
    MyInteger: xi.types.Scalar(dtype=xi.integer, alias='My Integer', manage=xi.Manage.INPUT)
    Indices: xi.types.Index(dtype=xi.integer, alias='Array Indices')
    Input: xi.types.Series(index=['Indices'], dtype=xi.integer, alias='Input Array')

    # Results need to be initialized in the run mode(s).
    # Entities are results if the manage attribute is xi.Manage.RESULT.
    Result: xi.types.Series(index=['Indices'], dtype=xi.real, manage=xi.Manage.RESULT, alias='Result Array')

There are a few things to note about the preceding code. For example:

• The name declared in this line of code: @xi.AppConfig(name="Quick Start with Python", version=xi.AppVersion(1, 0, 0)) is utilized as the application name on the tile displayed in the Xpress Insight HOME page.
• Also, in the example below, the scalar value assigned to the variable MyInteger is visible in the Entity Explorer next to the alias label.

  MyInteger: xi.types.Scalar(dtype=xi.integer, alias='My Integer', manage=xi.Manage.INPUT) 

  

In this example applications, entities that will be used in the application are declared at the top of the class declaration. You must:

• Define the data value type (dtype) for each entity.
• Define an index for each Series and DataFrame—For example, the input series references the indicies element in the line above.

  Indices: xi.types.Index(dtype=xi.integer, alias='Array Indices')
  Input: xi.types.Series(index=['Indices'], dtype=xi.integer, alias='Input Array')

Every Insight Python App must have a LOAD function and a RUN function defined. These are shown in the template file immediately after the declarations.

@xi.ExecModeLoad(descr="Loads input data.")
def load(self):
    # Scenario is being 'loaded' through Xpress Insight.
    # Insight automatically populates the parameters with the values from the UI.
    # Input entities will be captured and stored in the scenario.
    self.Input = pd.read_csv('input.csv', index_col=['Indices'], squeeze=True)
    self.Indices = self.Input.index
    self.MyInteger = self.Indices.size
    print("\nLoad mode finished.")

@xi.ExecModeRun(descr="Takes input data and uses it to compute the results.")
def run(self):
    # Scenario is being 'run' through Xpress Insight.
    # Insight automatically populates the parameters and inputs with the values from the UI.
    # Result entities will be captured and stored in the scenario.
    print('Scenario:', self.insight.scenario_name)

    # Calculate the results data.
    self.Result = self.Input * float(self.MyInteger)
    print("\nRun mode finished.")

@xi.ExecMode(name="CUSTOM_RUN", descr="Custom run execution mode.", clear_input=False)
def my_custom_run_mode(self):
    self.Result = self.Input * (self.MyInteger * 0.5)
    print("Custom run mode finished.")

When the run function is executed (for example by selecting Run on the Xpress Insight Scenario pill menu, or by clicking a run button in the interface), the entities marked as input are initialized for use, and the code stored in the run function is executed. The results are output to the RESULTS entities.

Result: xi.types.Series(index=['Indices'], dtype=xi.real, manage=xi.Manage.RESULT, alias='Result Array')

Note: Advanced users can also create custom run modes. @xi.ExecMode(name="CUSTOM_RUN", descr="Custom run execution mode.", clear_input=False) def my_custom_run_mode(self): self.Result = self.Input * (self.MyInteger * 0.5) print("Custom run mode finished.")

Finally, the Python program requires the main function.

if __name__ == "__main__":
    # When the application is run in test mode (i.e., outside of Xpress Insight),
    # first initialize the test environment, then execute the load and run modes.
    app = xi.create_app(InsightApp)
    sys.exit(app.call_exec_modes(["LOAD", "RUN"]))