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[DatabaseReference[ref],"cmd"]

evaluates cmd using the database specified by ref.

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
    "SQL"SQL database
    "SQL-JDBC"SQL database using JDBC
    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")
    "Target"the Target 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
  • The possible settings for target in ExternalEvaluate[{sys,"Target"target},] depend on sys, and include:
  • "path"path to a language executable
    DatabaseReference[]an SQL database connection
    SQLConnection[]an SQL-JDBC database connection
  • Typically, ExternalEvaluate uses the setting "ReturnType""Expression".
  • 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  (7)

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:

Evaluate a query in a database and return the result:

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

2+2

Scope  (18)

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:

For most systems, 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:

When using a database, the default return type is "Dataset":

"ReturnType" can be used to return data in a different form:

Evaluate code using a specified "Target":

When using a File with the "SQL" evaluator, the target can be a path to an SQLite file or a DatabaseReference specification:

Use "SessionProlog" to perform a side effect at the start of a session:

Use "Prolog" to perform a side effect before every evaluation:

Use "Epilog" to perform a side effect after every evaluation:

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  (5)

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:

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
Wolfram Research (2017), ExternalEvaluate, Wolfram Language function, https://reference.wolfram.com/language/ref/ExternalEvaluate.html (updated 2020).

Text

Wolfram Research (2017), ExternalEvaluate, Wolfram Language function, https://reference.wolfram.com/language/ref/ExternalEvaluate.html (updated 2020).

BibTeX

@misc{reference.wolfram_2020_externalevaluate, author="Wolfram Research", title="{ExternalEvaluate}", year="2020", howpublished="\url{https://reference.wolfram.com/language/ref/ExternalEvaluate.html}", note=[Accessed: 14-April-2021 ]}

BibLaTeX

@online{reference.wolfram_2020_externalevaluate, organization={Wolfram Research}, title={ExternalEvaluate}, year={2020}, url={https://reference.wolfram.com/language/ref/ExternalEvaluate.html}, note=[Accessed: 14-April-2021 ]}

CMS

Wolfram Language. 2017. "ExternalEvaluate." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2020. https://reference.wolfram.com/language/ref/ExternalEvaluate.html.

APA

Wolfram Language. (2017). ExternalEvaluate. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/ExternalEvaluate.html