Notebook

Hello, world!¶

As a first example, let's create a simple function in Intrepydd that prints the contents of a local array of integers. In Jupyter, we can write our Intrepydd program in a cell; to compile it, we'll need to save the contents of this cell to a file.

Prerequisites. Before starting, note that the Intrepydd compiler depends on the following Python packages:

typed_ast
cppimport
pybind11

In most Python implementations, you can install these packages by running the following system shell command:

In [ ]:

!pip install typed_ast cppimport pybind11

In addition, you should verify that the Intrepydd compiler is available in your environment. If you are running on our supplied environments, pyddc should be in your executable path; let's verify that next via another system shell command:

In [ ]:

!if ! [ -f "$(which pyddc)" ]; then echo "Can't find the Intrepydd compiler, 'pyddc'" ; else echo "Found the Intrepydd compiler: $(which pyddc)" ; fi

Creating the Intrepydd program¶

You need to store your Intrepydd code in a local file. From Jupyter, we can do so by placing that code inside a code cell, as we would with any Python code, and we can add the %%writefile magic at the top of the cell to tell Jupyter to write that content to a file (instead of executing it immediately).

Here's an example, which defines a function called easy_as() and writes its contents to an Intrepydd file called demo1.pydd. Go ahead and run this now.

Naming. The name of your .pydd file must be a valid Python module name. That is, later you will load your Intrepydd code using a Python import statement; therefore, the name of the file should be a valid name for importing, i.e., here, the name demo1 will be a valid name for the statement, import demo1.

In [ ]:

%%writefile demo1.pydd
# demo1.pydd

def easy_as():
    '''
    Prints a local array of integers.
    '''
    a = [1,2,3]
    for i in a:
        print(i)
        
# eof

To verify that this file is stored in the local working directory, let's issue a system shell command to list the available files. One named demo1.pydd should appear in this list.

In [ ]:

!ls -al

You can also verify that the written contents match what you put in the cell above, using the standard Jupyter magic command, %pycat:

In [ ]:

%pycat demo1.pydd

Compiling¶

Let's now run the Intrepydd compiler, pyddc, to convert this file into a static executable:

In [ ]:

!pyddc demo1.pydd

If everything went well, you should see a verbatim copy of your Intrepydd program as output. If there were any compilation errors, you'll see a message indicating that something went wrong.

For the end-May beta release, we'll provide pointers on how to carry out diagnostics in the event of errors.

Let's re-list the contents of the current directory:

In [ ]:

!ls -al

Intrepydd converts your Python-style program into a C++ program, which should appear as demo1.cpp. In addition, if the compilation succeeded without errors, then there will also be a binary shared library file. (The filename should have the form, demo1.*.so on Unix-style systems, including MacOS, or demo1.dll on Windows systems.)

If you know C++, you may find it intstructive to take a look at demo1.cpp or the compiler outputs, gcc.out and gcc.err, to get an idea of what Intrepydd can do under the hood.

Running the program¶

Now for the fun part: running your first Intrepydd program!

The compilation step created a new module containing your Intrepydd code. To use it, you first need to import it—as you would any Python module—and then you can call any function defined within it. The name of the module is the base name of the file (so base.pydd becomes a module named base).

In [ ]:

import demo1
demo1.easy_as() # Should print stuff!

In [ ]:

print(demo1.__doc__)

Caveats and known limitations¶

As of this v0.1 release, there is one limitation if you need to modify your Intrepydd code. Once your new module is compiled and loaded, you must terminate the kernel (Kernel $\rightarrow$ Restart) and re-run everything for any changes to take effect.

Summary and next steps¶

In short, the process of working with Intrepydd in Jupyter consists of the following steps:

Writing your Intrepydd subprogram in its own code cell, and writing its contents to a file.
Using the system shell to compile that program into a new module, which is stored locally as a dynamically loadable shared library.
Importing that new module and invoking its functions.

Once you think you've got the hang of these basic steps, you are ready to move on to the next demonstration.