# Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

Synchronously evaluate an expression in a separate kernel

Contributed by:
Richard Hennigan (Wolfram Research)

ResourceFunction["LocalEvaluate"][ evaluates | |

ResourceFunction["LocalEvaluate"][ wraps the head |

ResourceFunction["LocalEvaluate"] has attribute HoldFirst.

ResourceFunction["LocalEvaluate"][*expr*] automatically includes all definitions needed to evaluate *expr*, much like CloudEvaluate.

During the evaluation, the following events can be generated:

"TaskStarted" | task is started |

"FailureOccurred" | task could not be started |

"ScheduleTriggered" | scheduled task evaluation is beginning |

"MessageGenerated" | evaluation generated a message |

"PrintOutputGenerated" | evaluation generated print output |

"ResultReceived" | evaluation generated a result |

"ScheduleExecuted" | scheduled task evaluation is executed |

"TaskStatusChanged" | task status changed |

"TaskRemoved" | task is being removed |

With the specification HandlerFunctions→<|…,"*event*_{i}"→*f*_{i},…|>, *f*_{i}[*assoc*] is evaluated whenever *event*_{i} is generated. The elements of *assoc* have keys specified by the setting for HandlerFunctionsKeys.

ResourceFunction["LocalEvaluate"] initiates a new subkernel whenever it is called.

The following options can be given:

HandlerFunctions | <||> | how to handle generated events |

HandlerFunctionsKeys | Automatic | parameters to supply to handler functions |

IncludeDefinitions | True | whether to include any dependent definitions |

"ReturnDefinitions" | False | whether to send dependent definitions from the subkernel back to the parent kernel |

Initialization | None | an expression to be evaluated as part of the kernel initialization |

Asynchronous | False | whether to return a TaskObject instead of waiting for results |

ResourceFunction["LocalEvaluate"] uses WXF to transfer data between kernels, so the following BinarySerialize options can additionally be used to control serialization:

Method | Automatic | details of serialization methods to use |

PerformanceGoal | Automatic | aspects of performance to try to optimize |

Possible settings for PerformanceGoal include:

"Speed" | optimize for serialization and deserialization speed |

"Size" | optimize for size of data to be transferred |

Automatic | automatically pick serialization strategy |

Possible settings for Method include:

{typespec_{1}→enc_{1},…} | specify encodings for particular types |

Automatic | pick encodings automatically based on data |

Possible forms for the *typespec*_{i} include:

"PackedArrayIntegerType" | integer packed arrays |

"PackedArrayRealType" | real-valued packed arrays |

"PackedArrayComplexType" | complex-valued packed arrays |

Possible settings for "PackedArrayIntegerType" include "Integer8", "Integer16", "Integer32" and "Integer64" (64-bit systems only).

Run an evaluation in a separate kernel:

In[1]:= |

Out[1]= |

Compare to the current kernel:

In[2]:= |

Out[2]= |

Supply a head to be applied to the results of a local evaluation:

In[3]:= |

Out[3]= |

By default, definitions are included:

In[4]:= |

Out[2]= |

Do not include any definitions in the evaluation:

In[5]:= |

Out[5]= |

By default, definitions created on the subkernel are not returned to the current kernel session:

In[6]:= |

Out[2]= |

In[7]:= |

Out[7]= |

Return dependent definitions to the parent kernel for the output expression:

In[8]:= |

Out[2]= |

Now the definition of g is returned from the subkernel:

In[9]:= |

Out[9]= |

Only the definitions that the output depends on will be returned:

In[10]:= |

Out[2]= |

Since the output does not depend on f, its definition is not returned to the current session:

In[11]:= |

Out[11]= |

Compare to g, which appears in the output literally:

In[12]:= |

Out[12]= |

Specify an initialization that should evaluate first:

In[13]:= |

Out[13]= |

The initialization only runs on the other kernel; the current kernel is not affected:

In[14]:= |

Out[14]= |

Create a temporary init.m file and back up the original:

In[15]:= |

Out[16]= |

In[17]:= |

Using Automatic for Initialization is equivalent to using Get[FindFile["init.m"]]:

In[18]:= |

Out[18]= |

The symbol h is undefined otherwise:

In[19]:= |

Out[19]= |

Restore the original init.m file:

In[20]:= |

Out[20]= |

Create a large packed array of integers:

In[21]:= |

Pass a Method specification to the WXF serialization when sending expressions between kernels:

In[22]:= |

Out[22]= |

Use a smaller type to reduce transfer time:

In[23]:= |

Out[23]= |

By default, the smallest type that fits the data will be used:

In[24]:= |

Out[24]= |

Compare the size difference by using BinarySerialize:

In[25]:= |

Out[25]= |

In[26]:= |

Out[26]= |

By default, LocalEvaluate waits for results to be returned:

In[27]:= |

Out[27]= |

Set Asynchronous to True if you don't need to wait for results:

In[28]:= |

Out[28]= |

This is effectively equivalent to LocalSubmit when no definitions or initialization specifications are involved:

In[29]:= |

Out[29]= |

In[30]:= |

Out[30]= |

Discover symbols in a package without loading it in the current kernel:

In[31]:= |

Out[31]= |

The current kernel is unaffected:

In[32]:= |

Out[32]= |

Check how many symbols have been created in your current session that are not created by default:

In[33]:= |

Out[33]= |

Manipulate notebooks with a hidden front end:

In[34]:= |

Out[34]= |

Each evaluation of LocalEvaluate runs in a new kernel:

In[35]:= |

Out[35]= |

In[36]:= |

Out[36]= |

Compare to the current kernel:

In[37]:= |

Out[37]= |

Similar behavior to LocalEvaluate can be obtained by using TaskWait with LocalSubmit:

In[38]:= |

Out[38]= |

LocalEvaluate can often have better performance than LocalSubmit when sending/receiving large amounts of data:

In[39]:= |

Out[32]= |

In[40]:= |

Out[24]= |

In[41]:= |

Out[26]= |

In[42]:= |

Out[42]= |

Messages that are issued in the separate kernel are not printed in the current session:

In[43]:= |

Out[43]= |

In[44]:= |

Out[44]= |

Use HandlerFunctions to handle messages:

In[45]:= |

Out[45]= |

- Guide: Background & Scheduled Tasks
- Guide: Date & Time
- Guide: Using Connected Devices
- Workflow Guide: Managing Kernels

Wolfram Language 11.3 (March 2018) or above

- 2.0.0 – 27 January 2020
- 1.0.0 – 15 August 2018

This work is licensed under a Creative Commons Attribution 4.0 International License