Tags, Upset, UpValues ...

[Allan Hayes]

Here are some notes on Tags, Upset, UpValues ...that I hope may be
of help:

We are dealing with the following kinds of situations
In[1]:=Sin[s] = .3;
Set::"write": "Tag \!\(Sin\) in \!\(Sin[s]\) is Protected."
Explanation: Mma tried to store the rule under tag Sin, which is
Protected.

Here are three way out

1) Unprotect Sin; make the definition and then Protect Sin again.
In[2]:=Unprotect[Sin];
In[3]:=Sin[s]=.3;
In[4]:=Protect[Sin];

In[5]:=Sin[s]
Out[5]= 0.3

2) Store the rule under tag s using UpSet
In[6]:= Sin[s]^=.5; (*UpSet[Sin[s],.3] *)

In[7]:=Sin[s] (*uses new definition*)
Out[7]= 0.5

This is usually better because it does not cause the new rule to be
looked up every time Sin is used.

3) Store the rule under tag s using TagSet
In[8]:= s/:Sin[s]=.7; (*TagSet[s,Sin[s],.7]*)

In[9]:= Sin[s] (*new definition replaces old one*)
Out[9]= 0.7

The rules are stored in different ways according to how they are
entered.
In[10]:= DownValues[Sin]
Out[10]= {{HoldPattern[Sin[a]] :> 0.3, HoldPattern[Sin[s]] :> 0.3}

In[11]:= UpValues[s] (* Sin[s]^=.5 has been replaced*)
Out[11]= {HoldPattern[Sin[s]] :> 0.7}

They are stored as replacement rules because ultimately Mathematica
works by pattern matching and replacement.

You can see the more usual forms by using ? and ??
In[12]:=??Sin

"Sin[z] gives the sine of z."
Attributes[Sin] = {Listable, NumericFunction, Protected}

Sin[s] = 0.3

In[13]:=
?s
"Global`s"
Sin[s] ^= 0.7

There are also OwnValues, SubValues and NValues.Summary

***SUMMARY***

Here is a short rundown on making and storing rules, and on tags,
UpValues , Down Values etc.
r* means the value of r;
a --> b means that in the evaluation process a is changed to b;
s will always mean an unprotected symbol.

There are some additional points, for example to do with Conditions
that I shall not include.

I show the full forms on the left and the special forms on the right.

Set[s,r] --> Set[s, r*] ; (s=r)
add HoldPattern[s ]:> r* to the list OwnValues[s] (tag is s);
output r**

Set[f[g,h,..] ,r]--> Set[f*[g*,h*,..], r*] ; (f[g,h,..] = r)
add HoldPattern[f*[g*,h*,..]]:> r* to DownValues[f*] (tag is f*)
if f* = s[..] then
add HoldPattern[f*[g*,h*,..]]:> r* to SubValues[s] (tag is s )
output r**

UpSet[f[g,h,..] ,r]--> Set[f*[g*,h*,..], r*] ; (f[g,h,..] ^= r)
for each s that is a leftmost part of g* or h*
add HoldPattern[f*[g*,h*,..]]:> r* to UpValuesValues[s] (tag is s)
output r**

TagSet[s,f[g,h,..],r]-->TagSet[s,f*[g*,h*,..],r*] (a/:f[g,h,..]=r)
if f* =s then
add HoldPattern[f*[g*,h*,..]]:> r* to DownValues[s](tag is s);
if f* =s[..] then
add HoldPattern[f*[g*,h*,..]]:> r* to SubValues[s] (tag is s);
if s the leftmost part of at least one of g*,h* then
add HoldPattern[f*[g*,h*,..]]:> r* to UpValues[s] (tag is s);
output r**

If a rule cannot be stored because it has no suitably placed
unprotected symbol to use as tag then the evaluation proceeds except
the no rule is stored and a message is displayed; in particular,
the output is still generated.
The corresponding delayed versions SetDelayed, UpSetDelayed and
TagSetDelayed work similarly but do not evaluate r and they output
Null.

The lists DownValues, UpValues or SubValues are each ordered
according to the left sides of the rules, first by generality, then
by default ordering and then by order of introduction; if a rule is
added that has the same left side as an existing one then it
replaces the existing one

Entering ?f and ??f caused the the rules that have been stored
with the tag f to be printed out , but they use the familiar forms
like f[x_,y_] = r instead of HoldPattern[f[x_,y_] ]:> r.

Stored rules will be normally be used in the order
user defined OwnValues, inbuilt OwnValues
user defined UpValues, inbuilt UpValues
user defined DownValues, inbuilt DownValues
user defined SubValues, inbuilt SubValues
(please look up Appendix A.4.1 for more on this)
This is usually, but not always, the order is the same as shown by
? and ??

Allan Hayes
h...@haystack.demon.co.uk
http://www.haystack.demon.co.uk/training.html
voice:+44 (0)116 2714198
fax: +44 (0)116 2718642
Leicester, UK