Function Repository Resource:

FormalizeSymbols

Source Notebook

Convert symbols in an expression into formal symbols

Contributed by: Paco Jain (Wolfram Research)

ResourceFunction["FormalizeSymbols"][expr]

converts all symbols in expr whose context is $Context into unique formal symbols.

ResourceFunction["FormalizeSymbols"][expr,"Rules"]

returns the rules that would be used for replacement in ResourceFunction["FormalizeSymbols"][expr].

Details and Options

Formal symbols like a are standard Wolfram Language symbols that can not be assigned values. Using formal symbols prevents symbolic expression from unintentionally using values from the local environment.

Symbols are replaced with their formal counterparts when possible (and when doing so will not cause collisions between different symbols). If no formal counterpart exists, the symbol is not replaced unless the option setting "ExtraReplacements"→True is used. In that case, a random formal symbol not already used will be chosen as the replacement symbol.

ResourceFunction["FormalizeSymbols"] accepts the following options:

"EvaluateOnce"

False

whether to allow symbols with OwnValues to evaluate exactly once

"ExcludeInputSymbols

{}

a list of symbols to exclude from the left-hand side of replacement rules

"ExcludeTargetSymbols"

{}

a list of symbols to exclude from the right-hand side of replacement rules

"ExtraReplacements"

False

whether to replace symbols that lack a direct formal counterpart

"ReplacementContexts"

Automatic

a list of contexts whose symbols are to be replaced (or All)

"Verbose"

False

whether to print a message when non-standard replacments are made

ResourceFunction["FormalizeSymbols"] has the HoldFirst attribute to prevent evaluation of defined symbols in expr prior to replacement. However, in the special case that ResourceFunction["FormalizeSymbols"] is called directly on a bare symbol having an ownvalue, with the setting "EvaluateOnce"→True, the argument is allowed to evaluate exactly once to allow for intermediate variable assignment (see the second Properties and Relations example).

By default, ResourceFunction["FormalizeSymbols"] only replaces symbols in the current context, as given by $Context (typically having value "Global`"). To replace symbols from other contexts, use the option "ReplacementContexts".

Replaced symbols will always be in the System` context in the output regardless of the context in which they began.

Examples

Basic Examples (4)

Convert symbols to their formal counterparts:

In[1]:=

Out[1]=

FormalizeSymbols works on Latin, Greek and other symbols for which there exists a formal version in the Wolfram Language:

In[2]:=

$ResourceFunction["FormalizeSymbols"][\[Phi]/8]$

Out[2]=

In[3]:=

$ResourceFunction["FormalizeSymbols"][Cos[\[Sampi]]]$

Out[3]=

FormalizeSymbols works on both uppercase and lowercase letters:

In[4]:=

$ResourceFunction[ "FormalizeSymbols"][(r/A) \[Lambda] + \[CapitalLambda]]$

Out[4]=

FormalizeSymbols[expr,"Rules"] returns the rules that would be used for replacement in formalizing an expression:

In[5]:=

$ResourceFunction[ "FormalizeSymbols"][(r/A) \[Lambda] + \[CapitalLambda], "Rules"]$

Out[5]=

Scope (2)

By default, FormalizeSymbols does not affect symbols with multi-character symbol names:

In[6]:=

Out[6]=

To replace multi-character symbols as well, use the setting "ExtraReplacements"→True:

In[7]:=

Out[7]=

By default, FormalizeSymbols only affects symbols in the current context (here "Global`"). To allow replacement of symbols in other contexts, use the option "ReplacementContexts":

In[8]:=

Out[8]=

In[9]:=

Out[9]=

Options (11)

EvaluateOnce (2)

In the special case that FormalizeSymbols is directly called on a bare symbol having an own value, its argument can be allowed to evaluate exactly once using the option setting "EvaluateOnce"→True, as in the following case:

In[10]:=

Clear[a, b]
x = a + b;
ResourceFunction["FormalizeSymbols"][x, "EvaluateOnce" -> True]

Out[12]=

Without this top-level evaluation, the above inputs would result in x:

In[13]:=

Out[13]=

With "EvaluateOnce"→True, evaluation does not proceed beyond top-level:

In[14]:=

Clear[a, b, x]
z = x;
x = a + b;
ResourceFunction["FormalizeSymbols"][z, "EvaluateOnce" -> True]

Out[17]=

Contrast this result with using Evaluate, which triggers full evaluation:

In[18]:=

Out[18]=

ExcludeInputSymbols (1)

To exclude a given set of symbols from being replaced, use the option "ExcludeInputSymbols". Compare:

In[19]:=

Out[19]=

In[20]:=

Out[20]=

ExcludeTargetSymbols (1)

To exclude a given set of formal symbols as possible replacement characters, use the option "ExcludeTargetSymbols". Compare:

In[21]:=

Out[21]=

In[22]:=

$ResourceFunction["FormalizeSymbols"][x + i y, "ExcludeTargetSymbols" -> {\[FormalI]}]$

Out[22]=

ExtraReplacements (2)

By default, FormalizeSymbols does not replace symbols that lack a direct formal equivalent:

In[23]:=

Out[23]=

To replace all symbols, regardless of name, use the setting "ExtraReplacements"→True:

In[24]:=

Out[24]=

ReplacementContexts (4)

The default setting of "ReplacementContexts"→Automatic replaces only symbols in $Context (here Global`):

In[25]:=

Out[25]=

The "ReplacementContexts" option can be set to a list of contexts for which symbols should be formalized:

In[26]:=

Out[26]=

With the setting "ReplacementContexts"→All, symbols in any context other than System` are replaced:

In[27]:=

Out[27]=

FormalizeSymbols automatically avoids symbol collisions:

In[28]:=

Out[28]=

With the option setting "Verbose"→True a warning is issued about potential collisions:

In[29]:=

Out[29]=

Verbose (1)

With the setting "Verbose"→ True, a message is issued whenever a “non-standard” replacement is made, either due to potential collisions or due to replacement of a symbol that lacks a direct formal equivalent (as possible when "ExtraReplacements"→True):

In[30]:=