ExternalEvaluate

ExternalEvaluate["sys","cmd"]

evaluates the command cmd in the external evaluator sys, returning an expression corresponding to the output.

ExternalEvaluate[{"sys",opts},"cmd"]

uses the options opts for the external evaluator.

ExternalEvaluate[assoc,"cmd"]

evaluates cmd using the external evaluator specified by assoc.

ExternalEvaluate[session,"cmd"]

evaluates cmd in the specified running ExternalSessionObject.

ExternalEvaluate[sys"type",]

returns output converted to the specified type.

ExternalEvaluate[spec,obj]

evaluates the content of the specified File, URL or CloudObject.

ExternalEvaluate[spec,assoc]

evaluates the command specified by assoc.

ExternalEvaluate[spec,{cmd1,cmd2,}]

evaluates the list of commands cmdi.

ExternalEvaluate[spec]

represents an operator form of ExternalEvaluate that can be applied to a command or object.

Details

  • ExternalEvaluate[sys,"cmd"] returns either a string representing the result of evaluating cmd using the external evaluator system or a Failure object.
  • To be usable with ExternalEvaluate, language installations must have a standard 0MQ library installed for that particular language, as well as a "JSON" library.
  • In ExternalEvaluate[sys,obj], the contents of the external object obj will be used as the command. The external object can be File[], URL[], CloudObject[] or LocalObject[].
  • In ExternalEvaluate[sys,], possible choices of sys include:
  • "Python"Python
    "NodeJS"JavaScript running through Node.js
    "Julia"Julia
    "Ruby"Ruby
    "R"R
    "Jupyter"Jupyter kernel
    ExternalSessionObject[]session object started by StartExternalSession
  • In ExternalEvaluate[assoc,cmd], elements of the association can include:
  • "System"the external system or language to start
    "Version"version of the external system to use (e.g. "3.6")
    "Kernel"the Jupyter kernel name (e.g. "IFSharp")
    "Executable"the executable to use for evaluating code
    "ReturnType"type of object to return ("String", "Expression", ...)
    "Prolog"code to run before the command
    "Epilog"code to run after the command
    "SessionProlog"code to run before the session
    "SessionEpilog"code to run after the session
  • Possible settings for "type" in ExternalEvaluate[sys->"type",], or for "ReturnType", include:
  • "Expression"attempt to convert to a Wolfram Language expression
    "String"give the raw string output by the external evaluator
  • By default, ExternalEvaluate effectively uses the setting "ReturnType""Expression".
  • The interpreter used to convert the output depends on the system used. For Python, the default is "PythonExpression" and for JavaScript, the default is "JavaScriptExpression".
  • In the form ExternalEvaluate[{"sys",opts},], the possible options are the same as the elements for the association in ExternalEvaluate[assoc,].
  • ExternalEvaluate[sys,] is effectively equivalent to ExternalEvaluate[StartExternalSession[sys],].
  • The command "cmd" may contain an inline template expression <*expr*>. This evaluates expr before "cmd" is sent to the external evaluator.
  • ExternalEvaluate[sys,cmd] launches the external evaluator, evaluates cmd, then exits the external session.
  • ExternalEvaluate[session,cmd] sends the command to a running session and does not exit the session.
  • When sys is specified as a string, the session options used are searched first for user-specified options specified using RegisterExternalEvaluator, then from built-in session options included with the system or automatically discovered.
  • FindExternalEvaluators gives a dataset of evaluator systems that can be used.
  • For most external evaluators, individual write operations to standard output are immediately printed to the notebook or terminal.

Examples

open allclose all

Basic Examples  (6)

Evaluate a simple arithmetic expression in Python:

Evaluate a basic math function in JavaScript using Node.js:

Import a library in Python and use a function:

Evaluate multiple lines of code in a Python session:

A Julia dictionary is returned as an Association:

Use > at the beginning of a line to start an external code cell evaluated with ExternalEvaluate:

2+2

Scope  (11)

Compute powers of 10 using a range of numbers in Python:

Returning the result as a Python dict gives an Association:

Many Python types, like datetime, are natively mapped to Wolfram Language expressions:

Symbolically represent a function call and evaluate it:

Use the form "sys""String" to specify that results should be returned as strings, not converted into Wolfram Language expressions:

Manually convert the string result into its corresponding expression:

Start a session:

Add two numbers in Python using an inline TemplateExpression:

Delete the session using DeleteObject:

Import a file into a Node.js session:

Use functions defined by file:

Delete the session using DeleteObject:

Compute with complex numbers in Julia:

Put code in a cloud object:

Evaluate directly from the cloud:

Copy an example script to a CloudObject and execute the CloudObject in a session:

Use functions defined by the CloudObject file:

Delete the session using DeleteObject:

Copy a Python script file to a CloudObject and execute it locally:

Use the functions defined by the file:

Delete the session using DeleteObject:

Use "Prolog" to set the value of a variable before using it in the main code:

Applications  (5)

Start a Python session for use with NumPy:

Load the NumPy package:

Evaluate a NumPy library function:

A list of evaluations returns a list of results:

Use NumPy arrays:

Return a NumPy array:

Symbolically create a function in order to transfer data efficiently, which is very important when dealing with NumericArray:

Use Python with PIL and NumPy to generate a random image:

Write a function in Python to make it callable from the Wolfram Language:

Call the function with arguments:

Map the function on the Python side in order to improve efficiency:

Delete the ExternalSessionObject:

Export a list of Python functions to a file and load the file into a session with File:

Call the functions with arguments directly:

Define Wolfram Language functions to call the Python functions:

Delete the script and the session:

Deploy a simple web server using Node.js:

Read the result specifying a parameter:

Deleting the session will stop the server:

Properties & Relations  (8)

When an evaluation fails, a Failure object is returned:

The type of exception thrown is accessible inside the failure object:

In the form ExternalEvaluate["sys",], a new process is started with every evaluation:

For persistent evaluation, use StartExternalSession:

Each evaluation takes place in the same process:

Delete the session:

External language cells implicitly call StartExternalSession:

x=2

A new session has been started:

By default, all cells of a given system use that session:

x*x

End the session so that subsequent evaluations start in a new session:

The same session is used when running a list of commands:

Separate sessions are used in a list of separate ExternalEvaluate calls:

The default return type is "Expression":

Numbers, strings, lists and associations are automatically imported for the "Expression" return type:

The return type of "String" returns a string of the result in the external language:

Possible Issues  (1)

Unless given an ExternalSessionObject, each ExternalEvaluate call uses a separate session:

External language cells implicitly call StartExternalSession and use a single session:

x=3
x
Introduced in 2017
 (11.2)
 |
Updated in 2018
 (11.3)
2019
 (12.0)