Skip to main content

Rich Function View

RichFunctionView is an advanced UI editor to create a complex full-featured interface for your script.

It has all the features of the basic scripting. In addition, it allows you to:

To add input validators, actions or restrictions to a single script without building a multi-step workflow, wrap it in a one-step workflow with compactView: true: it opens in the same compact layout with the workflow features enabled.

When a form doesn't fit your model, build the view in code instead: see Custom function view.

Package dependency

Ensure that the Compute2 and WebComponents packages are installed

Enabling RichFunctionView UI editor​

To enable RichFunctionView, add editor: Compute2:RichFunctionViewEditor tag to your following code as it is shown:

rich-function-demo

Ensure computations are correct

Features of the RichFunctionView affect GUI only and do not affect computations. Use the RichFunctionView only when you are sure that the script works as expected.

Enhance inputs and outputs​

Visualize input data​

You can add viewers for input dataframes to review input data before starting computations, same way as for output viewers.

input-viewers

You can specify input viewer's properties to control their appearance. Viewer's properties are listed in the braces right after the viewer's name. A full list of the viewer's properties may be found by right-clicking on it and selecting the Properties... (dev tools) menu item.

Some options could be set directly in a chart annotaion via Grid(prop: val) syntax, however for many options a js viewer object must be used. To obtain js properties object a Dev Tools platform package must be installed. Right click on the chart, then To Script, then To JavaScript. The second argument is the properties object. For the purpose of directly using this object there is a viewersHook annotation. It must be a js function full name. Since viewer hook is synchronous, viewersHook function must just return another js function, which accepts the following arguments:

  1. ioName: string - name of the input or output
  2. type: string - viewer type
  3. viewer: DG.Viewer - viewer js object
  4. meta?: any - optional io metadata, available only in workflows.
function MyScriptViewersHookMaker() {
  return (ioName: string, type: string, viewer: DG.Viewer) => {
    viewer.setOptions(...)
  }
}

When used inside a workflow, the hook also receives a meta argument and is re-invoked whenever metadata published by meta links changes. See the workflow-side viewersHook reference for the full signature.

RichFunctionView supports the dockSpawnConfig option to control the viewer's width. By default, any viewer occupies all available space. Inside dockSpawnConfig there must be a json map with a viewer tab name and the following config.

interface DockSpawnConfigItem {
  'dock-spawn-dock-type'?: 'left' | 'right' | 'up' | 'down',
  'dock-spawn-dock-to'?: string,
  'dock-spawn-dock-ratio'?: number,
}

Viewer tab name is this context should match exactly (including spaces) the viewer name rendered in the app, for example a line chart for output named Trajectory will be Trajectory / Line chart. dock-spawn-dock-to is also using this naming convention.

viewers-block

Group scalar outputs​

You can use the category keyword to group scalar output parameters. In the case of output parameters, the category tag specifies the output tab used to show the output parameter values. The following code generates UI with three output tabs:

output-categories

tip

The view includes 4 tabs in total since there is a separate tab for input dataframe viewers.

Automatic script rerun​

You can run scripts automatically on UI opening and/or on any input change. This feature is useful for fast prototyping. We recommend using it only on fast Javascript scripts only to avoid repeatable runs of computational-heavy code.

The automatic function calls are not saved, so to save results to the run history you should press the Save button manually.

run-on-input

Form layout and run controls​

A few annotations control how the input form and the Run button are presented, without affecting computations.

Customize the Run button label​

Use meta.runLabel to change the text on the Run button. The default is Run. When the output is outdated after a previous run, the button automatically switches to Rerun regardless of this label.

Your script header
//meta.runLabel: Simulate

Render the input form as a tab​

By default the input form is docked on the left side of the view. Set meta.formAsTab to true to render it as a regular tab next to the output viewers instead.

Your script header
//meta.formAsTab: true

When formAsTab is enabled, dock-type hints from dockSpawnConfig on the inputs panel are ignored.

Workflow-oriented behavior​

The annotations below take effect whenever a script is rendered through RichFunctionView, but they are designed for workflow UX — where the user navigates between many steps and wants to focus on outputs. In a standalone single-script view they still work, but the use case is unusual.

Keep the Run button always available​

By default the Run button is hidden once the current run is up to date. Enable the rerun feature flag to keep it available, so the user can always launch a fresh run with the same inputs.

Your script header
//meta.features: {"rerun": true}

Inside a workflow the flag controls the Rerun button in the step's navigation toolbar (Back / Run / Next / Update). In standalone RichFunctionView the same flag keeps the in-form Run button visible after a completed run.

Hide inputs behind toggles​

In a workflow, inputs whose values are set by the workflow with the disabled or restricted restriction are hidden by default. A Show linked inputs (N) row on top of the form shows them. A link icon next to such an input says the value is the one the workflow set; once the value differs, the inconsistency icon replaces it. Inputs with info or no restriction stay visible. The standalone Rich Function View has no toggles and ignores meta.inputToggles and meta.inputsHidden.

Set meta.inputToggles to choose which inputs are hidden and how the rows read. Each entry is one row, Show <caption> (N), shown only while it hides something:

Your script header
//meta.inputToggles: [{"caption": "additional device params", "categories": ["Pump", "Valves"], "linked": true}, {"caption": "solver settings", "inputs": ["atol", "rtol"]}]
//input: double pumpRate {category: Pump}
//input: double atol = 1e-6
//input: double rtol = 1e-4
FieldMeaning
captionText of the row.
categoriesInputs whose category annotation is in the list.
inputsInputs by name. With categories, an input matching either is selected; without both, every input is.
linkedWith true, only selected inputs with the disabled or restricted restriction are hidden. Otherwise the selected inputs are hidden whatever their restriction.

An input belongs to the first entry that selects it. Entries with the same caption share one row, so adding {"caption": "linked inputs", "inputs": ["x"]} after the default entry puts an input without a restriction under the linked inputs row. The meta replaces the default [{"caption": "linked inputs", "linked": true}], and [] hides nothing.

To hide every input, set meta.inputsHidden to true. All inputs then go behind the Show linked inputs (N) row, linked or not, as with [{"caption": "linked inputs"}]. meta.inputToggles takes precedence over it.

Your script header
//meta.inputsHidden: true

Some inputs stay visible whatever the toggles say:

  • an input with errors or warnings, or with a value that differs from the one the workflow set;
  • an input with the keepVisible: true annotation, as in //input: double x {keepVisible: true}.

A dataframe input with the mutateOnly: true annotation and the restricted or info restriction has its form input disabled, so it can be edited in its viewers but not replaced. See Consistency.

An input with the hidden UI metadata stays hidden. The rows remember their state per function for the browser session, and apply to read-only steps too.

Provide custom docs and export data​

Add the readme​

You can add a customized readme file to your script. The linked Markdown file will be available by clicking icon on the ribbon panel. The readme file will appear inside the panel on the right side.

rfv-help

Export results​

You can use the one-click export feature to save the entire script run to a local file. To generate the export file, Select Export icon on the top panel. Automatic export saves all input and output values with their captions, units, and even viewers' screenshots.

To save the run's visible tables with their viewers as a project, select Save as project... in the same menu.

This feature is available for all scripts using the RichFunctionView. To disable it, add the meta.features tag to the script header.

export-demo

Customize export​

You can customize export using the following annotation:

//meta.customExports: [{"name": "pdf", "function": "MyPackage:MyPDFExport"}]

The export function will receive the following arguments:

  • funcCall: DG.FuncCall, current call.
  • startDownload: bool, true if the function should start a file download or just return results.
  • isOutputOutdated: bool, true if the function output is outdated.
  • validationState: Record<string, ValidationResult>, available only if run inside a workflows.
  • consistencyState: Record<string, ConsistencyInfo>, available only if run inside a workflows.

Declare these as //input: parameters of the export function. The current call must be typed funccall:

//name: MyPDFExport
//input: funccall funcCall
//input: bool startDownload
//output: object result
export function myPDFExport(funcCall, startDownload) {
  // build the report for funcCall; download it when startDownload is true
}

Workflows also support a workflow-level customExports option with a different handler signature (it receives the whole pipeline state, not a single call). See the workflow Custom exports reference for details.

Review and compare historical script runs​

Save a run​

To keep a run, click Save run on the top panel. In the Save run dialog:

  1. Pick where to save: My runs or a space, in the tree on the left or by opening its folders on the right. You can't save to a space you can only view.
  2. The right side shows what's already there: the space's subspaces as folders, then everything else in it, or your runs of this model in My runs. Click a run of this model in a space to overwrite it: Use this name takes its name, so saving replaces that run.
  3. Enter a Name, and optionally a Description and Tags, then click Save.

My runs lists all your runs of the model, including the ones you saved to spaces, and names can repeat there. The step runs a workflow saves with it aren't listed: open the workflow run instead. In a space, names are unique, ignoring case. If the space already has a run with the name, you're asked to replace it: the new run takes its place in the space, and the old run stays in its author's My runs and in other spaces. A name taken by another item in the space, such as a folder, can't be used.

After saving, the view title shows the model and the run name. It adds (edited) when you change an input. A saved run's inputs and results never change: saving again creates a new run.

Open a run​

To load a saved run, click Open runs panel on the top panel. The Runs panel works like a file browser:

  • The tree shows My runs and the spaces. The number next to each space is how many runs of the model are in it and in all its subspaces, each run counted once.
  • Selecting a space lists its subspaces as folders, then its own runs. Double-click a folder to open it, and .. or Backspace to go up. The path above the list leads back to any level.
  • A space linked into another space shows under both, with a link mark. Going up returns the way you came.
  • A search, tag or author filter finds runs in the selected space and all its subspaces, and the list shows where each run is. Clear filters goes back to the folder. In a space, each run shows its author, and the author filter appears when the runs have more than one author.
  • Favorites next to the search shows only your favorite runs, in the selected space and all its subspaces.
  • To add a space to your favorites, hover over it in the tree and click the star. The star next to Spaces shows only your favorite spaces and the spaces above them.

Double-click a run, or select it and click Open.

In the panel, you can also:

  • Click the star next to a run to add it to your favorites.
  • Edit details: change the name, description, and tags of a run you saved, or of a run in a space you can edit. The run keeps its author and save date, and the details show who edited it last. Edit one run at a time.
  • Add to space...: add a run from My runs to a space. The space links the same run, and it stays in My runs. Ctrl+click to add several runs at once: each keeps its name, a run already in the space is skipped, and a run with the same name as one in the space replaces it after a confirmation. A run can't be added when the space has a folder or file with its name, or when another selected run has the same name.
  • Delete a run in My runs, or Remove from space in a space you can edit, after a confirmation. Ctrl+click to select several runs first. Runs found by a filter are removed from the space each is in, so the selected runs have to be in the same space. A run deleted from My runs can't be restored there, and it stays in the spaces it was added to. A run removed from a space doesn't change.

To browse runs of all models, open the Model Hub and select Tools > Browse Runs.... It starts with All models, which lists the runs of every model in the Model Hub and shows each run's model. Pick a model to see only its runs. Compare takes runs of one model. To compare runs of different models, add them in the run comparison view. Ctrl+click several runs and click Open to open each of them in its own view. In the Runs panel of a model, Open loads one run into the view, so it's available only while one run is selected.

Compare historical runs​

To compare saved runs, Ctrl+click them in the Runs panel, then click Compare. To add the current, unsaved state instead, click Add the current state to a comparison on the top panel. Both open the same dialog, where you can change the name of each run for this comparison. When other comparisons are open, the dialog also lets you pick one or start a new run comparison. The dialog warns about outdated outputs of the current state. Saving the state later gives it its final name.

Model parameters optimization​

With RichFunctionView you can use the powerful built-in optimization functions.

High-intensity computation

Both Sensitivity analysis and Parameter optimization trigger many simultaneous runs of the model. We recommend using these features on fast Javascript and WebAssembly scripts to avoid repeatable running of heavy server-side code.

Sensitivity analysis​

Sensitivity analysis automatically runs the computation multiple times with varying inputs, and analyzes the relationship between inputs and outputs.

sens-analysis

Parameters optimization​

The parameters optimization solves an inverse problem to the sensitivity analysis: finding the input conditions that lead to a specified output of the model. It computes inputs minimizing deviation measured by loss function.

To enable parameters optimization, set the fitting feature flag:

Your script header
//meta.features: {"fitting": true}

Tuning fitting defaults​

You can override the parameter-fitting view's default settings with meta.fittingSettings. The value is a JSON object that is merged with the platform defaults at startup; anything you do not set keeps its default. The schema is defined alongside the optimizer in libraries/compute-utils/function-views/src/fitting/optimizer-api.ts.

Your script header
//meta.fittingSettings: {"method": "Nelder-Mead", "maxIterations": 200}