Ulam Programming Language

A Tutorial Introduction

Writing Ulam Code, Step By Step

0. Be on Ubuntu 12.04, 14.04, or 16.04
1. Add MFM PPA
2. Install the software
3. Write your first element
4. Generate a default signing key
5. Compile your element
6. Try it in the simulator
7. Next Steps

Be on Ubuntu 12.04, 14.04, or 16.04

Ulam is currently supported on Ubuntu LTS versions 12.04 (Precise Pangolin), 14.04 (Trusty Tahr), and 16.04 (Xenial Xerus). Other platforms, like Mint or Redhat, will require compiling from the github repo (see 'Cloning from github').

Add MFM PPA

Ubuntu supports the idea of personal package archives, PPA. Note that installing a package from a PPA allows the PPA owner to install arbitrary software on your machine. So you should trust the PPA owner.

The ulam and MFM software are available at ppa:ackley/mfm, where you can also find additional information about how to add a PPA to your Ubuntu system.

Here's how to do it from the commandline:

$ sudo add-apt-repository ppa:ackley/mfm
$ sudo apt-get update

If you prefer, you can do it through Synaptic Package Manager.

Settings->Repositories->Other Software->Add..

Even though the add repository window says include the entire deb line, all you need to put is ppa:ackley/mfm.

Install the software

The ulam package is all you need to install. It includes the MFM Simulator within it. (If you had the MFM Simulator installed previously when you install ulam it will replace the older installation.)

From the command line:

$ sudo apt-get install ulam
$

Or with Synaptic.

Note that ulam requires many other packages, such as the gcc compiler, so if your system is not already set up for programming the install may download hundreds of megabytes and take quite awhile.

Write your first element

Using your favorite version of emacs, create a file Mason.ulam containing the following text:

/** brick layer.
\symbol Ma
\color #00f
\symmetries all
*/

element Mason
{
  EventWindow ew;
  Void behave()
  {
    if(ew[1] is Empty)
    {
      Wall w;
      ew[1] = w;
      ew.swap(1,0);
    }
  }
}

Once you get that looking good, let's try to compile it:

$ ulam Mason.ulam
ERROR: No default handle, so cannot use '-' as handle (try 'mfzmake help'?)
$

It didn't work! We'll find out why in the next section.

Generate a default signing key

The ulam compiler can operate in several different modes, producing different kinds of output. By default, it wants to produce a .mfz file which is a compressed archive somewhat like a tar file, or a JAR file in Java. An mfz file can contain not just compiled ulam code, but also initial layouts for the simulator and other information, making an mfz file a useful all-in-one tool to share with others. However, because an mfz file contains executable code, each mfz file is cryptographically signed with a 'handle' to help identify the source of the code.

So when we tried to compile in the previous section, ulam complained it didn't know what handle to use to sign the mfz. The easiest thing for us to do is generate the signing key once and make it the default for ulam to use for all our work.

To generate a key, use the following command:

$ mfzmake keygen "elena s ackley"
Generated private key for 'elena s ackley' into /home/elenas/.mfm/private_keys/elena%20s%20ackley.priv
Generated public key for 'elena s ackley' into /home/elenas/.mfm/public_keys/elena%20s%20ackley.pub
Handle: elena s ackley (79ed-e5c-65f4)
$

In this example, the handle is elena s ackley, and the 79ed-e5c-65f4 is a fingerprint of the signing key. If you wish to share your mfz files with other ulam developers, you'll need to "publish" your handle and its fingerprint in some way that they can find it, such as your personal webpage, email signature, twitter feed, github profile...

For now, all we'll do is tell the ulam compiler to use this handle by default for signing mfz files.

$ mfzmake default "elena s ackley"
NOTE: 'elena s ackley' set as default handle
$

Compile your element

Let's try to compile again.

$ ulam Mason.ulam
$

It worked! If we want to get a bit more information about what the compiler is doing, we can use the '-v' switch:

$ ulam -v Mason.ulam
Default package signing handle: OK
MFZ package signing handle 'elena s ackley': OK
MFZ package to create: a.mfz
Compile Mason.ulam: OK
Element metadating Wall from /usr/bin/../lib/ulam/ulam1/bin/../share/ulam/core/Wall.ulam: OK
Element metadating Empty from /usr/bin/../lib/ulam/ulam1/bin/../share/ulam/stdlib/Empty.ulam: OK
Element metadating Mason from ./Mason.ulam: OK
Compile UlamCustomElements.cpp: OK
Compile Ue_10104Wall10.cpp: OK
Compile Ue_10105Empty10.cpp: OK
Compile Ue_10105Mason10.cpp: OK
Compile Uq_10104Fail10.cpp: OK
Compile Uq_1010919AtomUtils10.cpp: OK
Compile Uq_10109211EventWindow10.cpp: OK
Compile Uq_102323C2D10.cpp: OK
Create /home/elenas/WORK/ulam/repo/ULAM/ulam1/doc/wiki/demos/mason/.gen/bin/libcue.so shared library: OK
Create a.mfz package: OK
$

By default (as we can see at the end of the '-v' output) the ulam has written the file 'a.mfz'. To see what's inside this a.mfz, enter:

$ mfzrun a.mfz list
SIGNED BY RECOGNIZED HANDLE: elena s ackley (79ed-e5c-65f4)
FILES:
Path                                                                  Name                Size  Time
                                                                      MFZPUBKEY.DAT        279  Sat Jul 18 08:19:42 2015
usr/bin/../lib/ulam/ulam1/bin/../share/ulam/stdlib/                   EventWindow.ulam    2149  Fri Jul 17 13:12:14 2015
                                                                      Mason.ulam           218  Sat Jul 18 07:56:24 2015
usr/bin/../lib/ulam/ulam1/bin/../share/ulam/core/                     Wall.ulam            177  Fri Jul 17 13:12:14 2015
usr/bin/../lib/ulam/ulam1/bin/../share/ulam/stdlib/                   Empty.ulam           146  Fri Jul 17 13:12:14 2015
usr/bin/../lib/ulam/ulam1/bin/../share/ulam/stdlib/                   C2D.ulam            1796  Fri Jul 17 13:12:14 2015
usr/bin/../lib/ulam/ulam1/bin/../share/ulam/stdlib/                   Fail.ulam             76  Fri Jul 17 13:12:14 2015
usr/bin/../lib/ulam/ulam1/bin/../share/ulam/stdlib/                   AtomUtils.ulam      1523  Fri Jul 17 13:12:14 2015
home/elenas/WORK/ulam/repo/ULAM/ulam1/doc/wiki/demos/mason/.gen/bin/
libcue.so         118571  Sat Jul 18 08:19:42 2015
$

Try it in the simulator

Let's try it.

$ mfzrun  a.mfz

Unless you have a big monitor, the simulator display may not look good. The window restore button may help to resize the display. Type h on your keyboard to toggle showing the help panel.

To setup the run, use the pencil tool, select the 'Ma' symbol so it moves into the left position, and draw a single mason element (#00f blue) on the tile. Click space or de-select 'pause' and watch it run.

Describe the behavior of 'mason'.

When does the simulation reach a steady state?

Magnify the tile display until you can see the names of the elements.

Notice mason's Event Layer properties window. Using the 'Properties' tool, the one with the red dot and pointer, we click on an element to display its inside information, like we did here with mason.

Next Steps

Let's try to free the mason using the core element 'DReg' from the [Ulam Standard Library] (Ulam-Standard-Library). 'DReg' turns into 'Res', another core element, and occasionally may eat a 'Wall', also a core element.

Flood the grid with the DReg element using the bucket tool.

Use the 'General Destruction' slider to improve the chances that Walls are destroyed. Sliders adjust the four DReg model parameters.

Click Control-b to hide the buttons (alternatively they can be moved), and watch the element counts as they update.

What happens to the DRegs?

Does the Wall count change?

Is the mason freed?