# How Modules Work

The way modules work in *Mathematica* is basically very simple. Every time any module is used, a new symbol is created to represent each of its local variables. The new symbol is given a unique name which cannot conflict with any other names. The name is formed by taking the name you specify for the local variable, followed by , with a unique "serial number" appended.

The serial number is found from the value of the global variable $ModuleNumber. This variable counts the total number of times any Module of any form has been used.

Module generates symbols with names of the form x$nnn to represent each local variable. |

The basic principle of modules in *Mathematica*.

For most purposes, you will never have to deal directly with the actual symbols generated inside modules. However, if for example you start up a dialog while a module is being executed, then you will see these symbols. The same is true whenever you use functions like Trace to watch the evaluation of modules.

In[3]:= |

Out[3]= |

In[4]:= |

In[5]:= |

Out[5]= |

In[6]:= |

Out[6]= |

In[7]:= |

Out[7]= |

Under some circumstances, it is convenient explicitly to return symbols that are generated inside modules.

In[8]:= |

Out[8]= |

In[9]:= |

Out[9]= |

Unique[x] | generate a new symbol with a unique name of the form |

Unique[{x,y,...}] | generate a list of new symbols |

Generating new symbols with unique names.

The function Unique allows you to generate new symbols in the same way as Module does. Each time you call Unique, $ModuleNumber is incremented, so that the names of new symbols are guaranteed to be unique.

In[10]:= |

Out[10]= |

In[11]:= |

Out[11]= |

In[12]:= |

Out[12]= |

You can use the standard *Mathematica* ?name mechanism to get information on symbols that were generated inside modules or by the function Unique.

In[13]:= |

Out[13]= |

Symbols generated by Module behave in exactly the same way as other symbols for the purposes of evaluation. However, these symbols carry the attribute Temporary, which specifies that they should be removed completely from the system when they are no longer used. Thus most symbols that are generated inside modules are removed when the execution of those modules is finished. The symbols survive only if they are explicitly returned.

You should realize that the use of names such as for generated symbols is purely a convention. You can in principle give any symbol a name of this form. But if you do, the symbol may collide with one that is produced by Module.

An important point to note is that symbols generated by Module are in general unique only within a particular *Mathematica* session. The variable $ModuleNumber which determines the serial numbers for these symbols is always reset at the beginning of each session.

This means in particular that if you save expressions containing generated symbols in a file, and then read them into another session, there is no guarantee that conflicts will not occur.

One way to avoid such conflicts is explicitly to set $ModuleNumber differently at the beginning of each session. In particular, if you set $ModuleNumber=10^10 $SessionID, you should avoid any conflicts. The global variable $SessionID should give a unique number which characterizes a particular *Mathematica* session on a particular computer. The value of this variable is determined from such quantities as the absolute date and time, the ID of your computer, and, if appropriate, the ID of the particular *Mathematica* process.

$ModuleNumber | the serial number for symbols generated by Module and Unique |

$SessionID | a number that should be different for every Mathematica session |

Variables to be used in determining serial numbers for generated symbols.

Having generated appropriate symbols to represent the local variables you have specified, Module[vars, body] then has to evaluate body using these symbols. The first step is to take the actual expression body as it appears inside the module, and effectively to use With to replace all occurrences of each local variable name with the appropriate generated symbol. After this is done, Module actually performs the evaluation of the resulting expression.

An important point to note is that Module[vars, body] inserts generated symbols only into the actual expression body. It does not, for example, insert such symbols into code that is called from body, but does not explicitly appear in body.

"Blocks and Local Values" discusses how you can use Block to set up "local values" which work in a different way.

In[17]:= |

Out[17]= |

Most of the time, you will probably set up modules by giving explicit *Mathematica* input of the form Module[vars, body]. Since the function Module has the attribute HoldAll, the form of body will usually be kept unevaluated until the module is executed.

It is, however, possible to build modules dynamically in *Mathematica*. The generation of new symbols, and their insertion into body are always done only when a module is actually executed, not when the module is first given as *Mathematica* input.

In[18]:= |

Out[18]= |