Offscreen interactivity math messages

Offscreen Websocket mode fully supports math interactive features. This page describes the corresponding WebSockets messages.

These messages rely on a math solver controller on the server that mainly allows you to handle:

  • Variable management.
  • Math expression solving.
  • Diagnostic to help troubleshoot common pitfalls on a given task and the specified block.
  • Evaluation of a block expression to get plot-ready coordinates.

They consist in two messages: a mathSolver to perform an action on the math solver controller and its corresponding response mathSolverResult.

Sending a message to the math solver on the server

Client to server message
{
  "type": "mathSolver",
  "action": [enum] "available-actions" | "numerical-computation" | "get-diagnostic" | "get-variables" | "set-variable-value" | "get-variable-value" | "remove-variable-value" | "as-variable-definition" | "get-variable-definitions" | "get-evaluables" | "evaluate",
  "blockId": [string] <the block id>,
  "task": [string] <the action for which a diagnostic is requested>,
  "variableName": [string] <the variable name>,
  "variableValue": [double] <the variable value>
  "evaluation": {
    inputVariableName: [string] <the input variable name>,
    outputVariableName: [string] <the input variable name>,
    from: [double] <the start of the range to evaluate>,
    to: [double] <the end of the range to evaluate>,
    pointCount: [int] <the number of values to evaluate between [from, to]>
  }
}

Getting a result message from the math solver on the server

The server sends you a mathSolverResult containing the math solver result.

Server to client message
{
  "type": "mathSolverResult",
  "action": [string] <the action requested in mathSover message>,
  "result": [Object],
  "blockId": [string] <the block id>
}

Message details per action

available-actions

Returns the available actions for the specified block.

  • Its input is the blockId.
  • Its result is an array of available actions. Ex: “numerical-computation”

numerical-computation

Returns the output for the numerical computation of the specified block.

  • Its input is the blockId.
  • Its result is a string representing the output formatted in JIIX.

get-diagnostic

To help troubleshoot, the get-diagnostic gives you diagnostics on a given task and the specified block. It can be useful to understand why get-evaluables returns an empty array, by calling it with an evaluation task or to find out why available-actions does not include the numerical-computation action in the returned array, by calling it with a numerical-computation task.

It also returns a MathDiagnostic code so that your application can get information about error situations, such as computation errors, and that you can map to an error message in your application to let end users know what's going on.

  • Its input are the blockId and task: given action, for example “numerical-computation”.
  • Its result is a MathDiagnostic value.

get-variables

Returns information about defined variables, associated with the specified block or from global variables.

  • Its input is the blockId.
  • Its result is a map of key/value, with key: variable-names, value: math variable information (name, source type, source id, occurrence count, value).

set-variable-value

Sets the value associated with the given variable name, for the specified block or as global variable.

  • Its input are the blockId, the variable name, and the value to set.
  • Its result is empty.

get-variable-value

Returns the value associated with the given variable name, for the specified block or as global variable.

  • Its input are the blockId, and the variable name.
  • Its result is the variable value

remove-variable-value

Removes the definition of the given variable name, for the specified block or as global variable.

  • Its input are the blockId, and the variable name.
  • Its result is empty.

as-variable-definition

Checks if the specified block represents a variable definition and returns the associated information.

  • Its input is the blockId.
  • Its result is the name and value of the defined variable if any, otherwise it is empty.

get-variable-definitions

Returns the list of all variable definitions.

  • Its input is the blockId.
  • Its result is an array of name and value of the variables of the block.

get-evaluables

Returns the list of variable names that can be evaluated in the specified block. An expression is evaluable if it can be interpreted as a function of a given variable:

  • The expression can be a simple expression with a single unknown variable Example “cos(x)”, in which case the output variable will have an empty name.
  • It can also be an equation with two unknown variables, at least one of which occurs only once in the expression Example “y = x² + 2x”.
  • Or a constant expression with a single unknown variable Example “y = 4/3”, in which case the input variable will have an empty name.

The message content is:

  • Its input is the blockId.
  • Its result is an array of input name (name of the varying variable) and output name (name of the result variable).

evaluate

Returns the list of points resulting from evaluating the given variables in the specified block. This allows to get plot-ready coordinates that can be used to plot graphs using a graphics library.

  • Its input are the blockId, the input/output math variables used for evaluation (input variable name, output variable name), from: the start of the range to evaluate, to: the end of the range to evaluate, pointCount: the number of values to evaluate between from, to.
  • Its result is an array array of evaluated points for each continuous parts of a curve.