(Under construction)

xAct`xCore`

Author

© 2007-2018, under the GNU General Public License (GPL)

José M. Martín-García

jose@xact.es

Intro

xCore` contains a collection of programming tools for the xAct` framework for Tensor Computer Algebra in Mathematica. There is no mathematical knowledge in this package.

Load the package

This loads the package from the default directory, for example $Home/.Mathematica/Applications/xAct/ for a single-user installation under Linux. The external package ExpressionManipulation` is automatically loaded as well:

<<xAct`xCore`

1. Directories

There are several possible places to install the xAct` distribution. The companion notebook Directories.nb explains the possibilities for the Linux, Windows and Mac environments. Here we assume that the package has been loaded from one of those recommended places.

The installation directory is stored in the variable

$xActDirectory

and the documentation directory is

$xActDocDirectory

2. Versions

Each one of the xAct` packages has its own version variable.

The current xCore` version is given by the pair

$Version

The first element of the list contains the version number as a string with three integers:

InputForm[First[%]]

The second element is a date list { year, month, day } :

InputForm[Last[%%]]

When packages are loaded, there are some checks of the versions of the needed packages. These checks are performed comparing the dates only.

3. The GPL License

All xAct` packages are distributed as free software under the GNU General Public License (GPL) . The full document of the license is included in the gpl.txt file in the distribution. A particularly important part is contained as a Disclaimer in the packages.

Each package has its own Disclaimer command:

Disclaimer[]

4. Messages

Many commands in xAct` send messages, using the built-in Message, usually to report all kinds of errors. Many of those messages only affect particular functions, and are hence defined with those functions. More general messages, common to many of those functions, are defined in xCore`.

These are messages which could come from many different functions in the system:

General::versions

General::unknown

General::invalid

General::noundef

General::nouse

General::empty

General::notyet

General::missing

General::undef

This is the generic error message:

General::error

All those error messages are activated by default. There are some other messages which are not errors, but only warnings. They are handled through a particular type of message.

The general warning message is:

General::warning

By default it is deactivated. We activate it  with

On[General::warning]
General::warning

Its second argument must be the global variable $WarningFrom, reporting on the part of the code in which the problem has been found, through Block constructs. When the problem cannot be localized we get the default General:

$WarningFrom

For instance:

Block[{$WarningFrom="xCoreDoc"},Message[General::warning,"Testing message",$WarningFrom]]

5. Developing tools

5.1. CheckOptions

5.2. SetNumberOfArguments

Following Mathematica, we throw error messages when public functions are used with an unexpected number of arguments. Mathematica already has named messages for this purpose, but there is no (as far as I know) a simple driver to use them, and so we introduce it.

A function with two arguments:

SetNumberOfArguments[f,2]

Now we get error messages unless we use the function with exactly two arguments. Not that there are different messages:

f[]

f[1]

f[1,2]

f[1,2,3]

A function can have different numbers of arguments. We have only prepared a "range" notation:

SetNumberOfArguments[g,{2,3}]

g[]

g[1]

g[1,2]

g[1,2,3]

g[1,2,3,4]

Possible values are 0 and Infinity, the latter used when the function accepts options.

Clean up:

Remove[f,g]

5.3. Manipulation of lists

5.4. Evaluation

6. String formatting

6.1. Underline

Given a string, we want to underline it. This will be frequently used in xTensor` to denote pattern indices in StandardOutput.

Any string can be underlined:

Underline["hello"]

FullForm[%]

Any string can be underlined, even one containing blanks:

Underline["x y"]

FullForm[%]

The only case not accepted is the empty string:

Catch@Underline[""]

A second argument can be used to color the line under the symbol:

Underline["hello",RGBColor[0,0,1]]

Underline["hello",Hue[0]]

Note that Underline uses strings, and so there is no creation of symbol:

?hello

6.2. TildeString

In other ocassions we want to add tildes above or below a string. This happens often with Astekhar's notation for densities, where the number of strings denotes the weight.

A positive number means tildes above the string:

TildeString["x",3]

FullForm[%]

A negative number means tildes below the string:

TildeString["x y",-3]

Again, we can use a second argument to color the tildes:

TildeString[TildeString["x",1,Hue[0]],-1,Hue[0.3]]

The empty string is an exception:

Catch@TildeString["",2]

6.3. ColorString

Sometimes it is the string itself what we want to color.

Example:

ColorString["hello",Hue[0]]

FullForm[%]

Now the empty string is not an exception:

ColorString["",Hue[0]]

6.4. HatString

Or we may want to add hats.

A positive number means hats above the string:

HatString["x",3]

FullForm[%]

A negative number means hats below the string:

HatString["x y",-3]

Again, we can use a second argument to color the tildes:

HatString[HatString["x",1,Hue[0]],-1,Hue[0.3]]

The empty string is an exception:

Catch@HatString["",2]

7. xUpValues

xCore` imitates a number of Mathematica functions for setting values, with the only difference that they unprotect (and later protect again) protected symbols. They are denoted with the Mathematica name prepended with an x.

Let us protect symbol x:

Protect[x]

This does not work:

UpSet[f[x],1]

but this does create an upvalue:

xUpSet[f[x],1]

?x

The pair TagSet and TagSetDelayed has also been generalized, but with a different syntax, because Mathematica's syntax is inconsistent. Let us first see what is the problem:

The difference between the *Set and the *SetDelayed functions is that the former have attribute HoldFirst while the latter have attribut HoldAll. This means that in the former case the RHS is evaluated before the assignment and in the latter case the RHS is evaluated at evaluation. This is not the case for TagSet:

First/@Attributes/@{Set,UpSet,TagSet}

First/@Attributes/@{SetDelayed,UpSetDelayed,TagSetDelayed}

I think this is because TagSet needs to hold its two first arguments, and so HoldFirst wouldn't be enough. Hence, I have grouped the two first arguments in a list:

xTagSet[{x,f[x]},Random[]]

?x

xTagSetDelayed[{x,f[x]},Random[]]

?x

We have also created the generalization of similar constructs which do not exist in Mathematica.

There is AppendTo, but not UpAppendTo:

?AppendTo

?UpAppendTo

We have created xUpAppendTo:

xUpSet[f[x],{1,2,3}]

xUpAppendTo[f[x],4]

?x

Equivalently, there is DeleteCases, but no DeleteCasesTo or UpDeleteCasesTo. We have created xUpDeleteCasesTo:

xUpDeleteCasesTo[f[x],3]

?x

8. Rules

8.1. FoldedRule

We prepare a way to "compose" a sequence of lists of rules. This will be useful in the package xCoba`.

frule=FoldedRule[{x->a,y->a+b},{a->3,b->5}]

?FoldedRule

9. Names

10. Final comments

Note: For further information about xCore`, and to be kept informed about new releases, you may contact the author at  jose@xact.es. Suggestions and comments are welcome and very much appreciated!
This is xCoreDoc.nb, the docfile of xCore`, currently in version 0.6.9.

?xAct`xCore`*