Larch Overview

Larch is a scientific data processing language written in python and designed to be

• easy to use for novices.
• complete enough for intermediate to advanced data processing.
• data-centric, so that arrays of data are easy to manage and use.
• easily extensible with python.

Larch makes use of many great efforts in Python, especially for scientific computing.

Larch uses numpy for all its numerical heavy lifting, so that processing arrays of data is easy and fast. Larch also uses scipy, a vast set of library for advanced numeric capabilities, such as linear algebra, fast Fourier transforms, signal processing, special functions, and non-linear least squares minimization. For high-quality graphics, larch uses the fantastic matplotlib library, and uses wxPython for GUIs.

More detailed documentation can be found at http://xraypy.github.com/xraylarch/

The rest of this documentation is left for historical reasons....

Features

Larch is a full featured programming language intended to be used as a "macro language" to glue together scientific computations and data manipulations. The syntax (and implementation) of Larch is heavily indebted to Python, an excellent language with a strong reputation for cleanliness and ease of use.

More detailed documentation

Variables

As with other programming languages, variables are named quantities used to hold data. In Larch, a variable may contain any of the following data types: integers, real numbers, complex numbers, strings, lists, dictionaries (hashes), and multidimensional arrays of numerical data. Larch does not associate a variable's type with its name, and does not require the type of a variable to be specified. A variable name must start with a letter or '_', followed any number of letters, numbers, and '_'. Variable names are case-sensitive.

To assign a value to a variable, you would say:

   1     larch> x = sqrt(90) -2.
   2     larch> print x
   3     7.48683298051

Where the '=' sign indicates the assignment, and the value of the variable of the left-hand-side of the '=' sign is set to the value of the expression on the right-hand-side of the '='.

Once they exist, variables can be used in expressions:

   1     larch> x_squared = x * x
   2     larch> print x_squared
   3     56.052668078

Array data (that is, sequences of numbers) and strings (sequences of characters) can be accessed either element-by-element or with slices:

   1       larch> arr = arange(10)    # simple array
   2       larch> print arr
   3       [0 1 2 3 4 5 6 7 8 9 10]
   4       larch> print arr[3]
   5       3
   6       larch> print arr[2:8]
   7       [2 3 4 5 6 7]
   8 
   9       larch> str = 'here is a string'
  10       larch> print str[0:6]
  11       here i

Groups and Namespaces

Data often comes with many related quantities, typically with different types. In larch, variables aregrouped together into sets of variables called Groups. Besides having a name, a group is really just a convenient way to associate different variables with one another.

But since each group has a name, each variable really has a hierarchy of names: a variable name and one or more group names. The different parts of the name are separated by a '.', so that a full name for a variable might be 'group1.energy' or 'dataset1.x'. Groups can also be nested, giving names like 'group.subgroup.subsubgroup.value'.

As in the examples above, it is not always necessary to refer to variables by their full name. Unqualified names (ie, those without a 'group.' prefix) will be searched for in a list of groups. In addition, there is always a "Local Group" which is the first group looked in, and where new variables will be placed. At startup, the Local Group is '_main', but this can be changed, as we'll see below.

   1      larch> x = 1
   2      larch> group1.x = 3.3
   3      larch> print x, _main.x, group1.x
   4      1 1 3.3

In addition to _main, there are a few other groups at startup: _builtin holds constants and builtin functions, _sys holds program state information, and _math holds many of the basic mathematical functions. This _builtin group is special in that it cannot be easily altered from larch directly.

Complete and clean syntax for programming

Larch syntax is python-like, with some exceptions. Most importantly, indentation doesn't matter, and blocks end with 'end' statements. A typical for-block will look like this:

   1        for i in range(10):
   2            print i
   3        endfor

There are also while blocks and if-elif-else blocks:

   1        n = 0
   2        while n<10:
   3           print ' n = ',n
   4           if n==3: print 'here is 3!!'
   5           n = n + 1
   6        endwhile
   7 
   8        if n > 10:
   9           print 'No'
  10        elif n > 5 and n < 8:
  11           print 'Maybe'
  12        else:
  13           print 'Yep'
  14        endif

A design goal is that well-formed larch code should be very easy to translate into valid python (and vice versa).

user-defined functions (aka procedures)

• User defined functions can be written in larch:

   1         def  myfunc(arg1, option='test'):
   2             'documentation string'
   3             print 'this is my funcition ', arg1
   4             print 'optional param = ', option
   5             if type(option) != 'string':
   6                  print 'option must be a string!!'
   7                 return False
   8             endif
   9             value = sqrt(arg1)
  10             x.tmp = value
  11             return value > 10.
  12         enddef

Which could be called as

   1         larch> ret = myfunc(3., option = 'xx')
   2         larch> print ret, x.tmp
   3         False 1.73205080757

Other features:

• load() function:
  • you can run a file of larch commands with the load() function:

       larch> load('myfile.larch')

Differences between Larch and Python

Larch deliberately borrows heavily from python's syntax. In fact, the implementation of larch depends uses Python's own parsing and interpreting tools, so that we did not need to carefully craft a full language specification.

This similarity in syntax makes the implementation of Larch very simple, but more or less requires very similar syntax. We view this as a happy accident, but not necessarily the main goal, which was to make a numerical "macro" language easy enough for non-programming scientists to use casually. So there are deliberate differences between Larch and Python:

• Larch DOES NOT ENFORCE indentation. Instead, code blocks are ended with 'end***' (if / endif , for/endfor, def/enddef, try/endtry). This is probably the most significant difference between larch and Python.
• Larch has many more builtins and assumes data is a numerical array
• whenever possible. Because it is assumed that many functions and datasets will be available in a session, Larch uses slightly different "name lookup" rules from Python. Larch uses distinct namespaces are use

  heavily, in the form of Larch Groups. But to avoid the namespace mess of doing

   1   from module import *

• while still giving simpler, implicit access to the large number of

  functions and datasets, Larch instead keeps a list of Groups to search through for name resolution. This list can be manipulated by the user.

Now, if you're a Python purist, these two points probably seem dreadfully Wrong. Fine, don't use Larch: use Python. Did we mention this is meant as a domain-specific macro language

And now, here are some especially cool Python-enabled features of Larch:

• Larch data are actually Python objects. Thus, any Python methods come for free:

   1    Larch> mystring = "Hello World"
   2    Larch> print mystring.split()
   3    ['Hello', 'World']

• Python modules can be imported and used directly in Larch. Need to do socket communication?

   1    Larch> import socket
   2    Larch> print socket.gethostname()
   3    mymachine