Remote Definitions

Parallel kernels do not have access to the values of variables defined in the master kernel, nor do they have access to locally defined functions.

Mathematica contains a command DistributeDefinitions that makes it easy to transport local variables and definitions to all parallel kernels. The main advantage of this method is that the application package does not need to be installed on the remote kernels. All definitions are sent through the existing connection to the remote kernels.

Distributing Definitions

DistributeDefinitions[s1,s2,...]distribute all definitions for symbols to all remote kernels
DistributeDefinitions["Context`"]distribute definitions for all symbols in the specified context

Distributing definitions.

DistributeDefinitions has the attribute HoldAll to prevent the evaluation of the symbols.

DistributeDefinitions exports the following kinds of definitions: OwnValues, DownValues, , UpValues, , .

DistributeDefinitions sets the attributes of the remote symbols equal to the locally defined attributes, except for attributes such as Protected and Locked.

Any old definitions existing on the remote side are cleared before the new definitions are made.

Examples

Start several parallel kernels.
In[24]:=
Click for copyable input
Out[24]=
Define a variable with a value and a function with attributes.
In[25]:=
Click for copyable input
In[26]:=
Click for copyable input
The remote kernels do not know the symbol , as demonstrated with the next evaluation.
In[28]:=
Click for copyable input
Out[28]=
Here is a subtle point. The following remote evaluation seems to work, even though the symbols are not defined on the remote side.
In[29]:=
Click for copyable input
Out[29]=

The reason is that the remote kernels return the unevaluated expression , because the function and variable are not defined on the remote kernel. The master kernel evaluates the returned results further, but it does so sequentially.

You can easily produce an example where the difference between remote and local evaluation becomes apparent.

On the local kernel, the symbol evaluates to , and the Head of is Integer.
In[30]:=
Click for copyable input
Out[30]=
On the remote kernels, stays a symbol, and its head is Symbol.
In[31]:=
Click for copyable input
Out[31]=
You can export the local definitions to the remote kernels.
In[32]:=
Click for copyable input
Now the remote evaluation gives the same result as the local one.
In[33]:=
Click for copyable input
Out[33]=

Automatic Distribution of Definitions

Higher-level parallel commands, such as Parallelize, ParallelTable, ParallelSum, ... will automatically distribute definitions of symbols occurring in their arguments.

For this parallel table, the function and the iterator bound will evaluate on the subkernels, so their definitions need to be distributed to make it work.
In[1]:=
Click for copyable input
In[3]:=
Click for copyable input
Out[3]=

This automatic distribution happens for any functions and variables you define interactively, within the same notebook (technically, for all symbols in the default context). Definitions from other contexts, such as functions from packages, are not distributed automatically.

A symbol from a context other than the default context is not distributed automatically.
In[4]:=
Click for copyable input
As a result, the symbol is returned unevaluated from the remote kernels, and is evaluated only after the parallel computation is done, where $KernelID is zero.
In[5]:=
Click for copyable input
Out[5]=
You can distribute such symbols using DistributeDefinitions.
In[6]:=
Click for copyable input
In[7]:=
Click for copyable input
Out[7]=

Distributing Contexts

DistributeDefinitions["Context`"] exports all definitions for all symbols in the given context. Thus, you can use the following to make all your interactively entered definitions known to the remote kernels.

In[11]:=
Click for copyable input
Out[11]=

Exporting the context of a package you have loaded may not have the same effect on the remote kernels as loading the package on each remote kernel. The reason is that loading a package may perform certain initializations and it may also define auxiliary functions in other contexts (such as a private context). Also, a package may load additional auxiliary packages that establish their own contexts.

DistributeDefinitions["Context`"] is useful for exporting contexts for definitions that you have explicitly set up to be used on remote kernels. There is a separate command ParallelNeeds for remote loading of packages.

clears any definitions for symbols in the context on remote kernels.

Loading Packages on Remote Kernels

ParallelNeeds["Context`"]evaluate Needs["Context`"] on all available parallel kernels

Loading packages.

ParallelNeeds["Context`"] is essentially equivalent to ParallelEvaluate[Needs["Context`"]], but it is remembered, and any newly launched remote kernels will be initialized as well.

Exporting the context of a package you have loaded may not have the same effect on the remote kernels as loading the package on each remote kernel with ParallelNeeds[]. The reason is that loading a package may perform certain initializations, and it may also define auxiliary functions in other contexts (such as a private context). Also, a package may load additional auxiliary packages that establish their own contexts.

The next two commands load the Mathematica package on the master kernel and all remote kernels.
In[12]:=
Click for copyable input
In[13]:=
Click for copyable input

Note that Mathematica packages available to the master kernel may not be available on remote kernels from older versions of Mathematica.

Example: Eigenvalues of Matrices

Definitions

The parameter gives the desired precision for the computation of the eigenvalues of a random × matrix.
In[1]:=
Click for copyable input
The function generates a random × matrix with numeric entries.
In[2]:=
Click for copyable input
The function measures the time it takes to find the eigenvalues.
In[3]:=
Click for copyable input
It is enough to distribute the definition of the main function . Any values it depends on will be distributed automatically.
In[4]:=
Click for copyable input
Out[4]=

A Sample Run

Here you measure the time it takes to find the eigenvalues of 5×5 to 25×25 matrices. Because the computations may happen on remote computers that differ in their processor speeds, the results do not necessarily form an increasing sequence.
In[5]:=
Click for copyable input
Out[5]=
Alternatively, you can perform the same computation on each parallel processor to measure their relative speed. Here you find the speed of calculation of the eigenvalues of a 20×20 matrix on each of the parallel processors.
In[6]:=
Click for copyable input
Out[6]=
New to Mathematica? Find your learning path »
Have a question? Ask support »