Torsten’s Opusmodus Tools (TOT)

This library provides a collection of definitions that extend the algorithmic composition system Opusmodus.

Disclaimer

In principle, this library can now be loaded into Opusmodus version 3, but Opusmodus 3 is currently only partially supported and untested.

• This library was initial developed for Opusmodus 2, and some functionality may not work anymore. (Opusmodus keeps changing the interface of functions etc.)
• For installing the dependency cluster-engine (see below), you currently need to use the cluster-engine git branch optimisations. (That branch has been updated to work with the version of the different Lisp compiler that Opusmodus 3 now uses, but those changes are not yet merged into the cluster-engine master branch.)

Also, note that these tools have been developed for personal use for specific projects, and therefore their generality (or even applicability) for other projects might be limited :)

Nevertheless, I trust at least some of the various functions here might be useful for others. Note that I always documented their purpose and limitations and included many usage examples.

Documentation

You can browse the documentation of this library online at https://tanders.github.io/tot/. However, remember that you can directly evaluate the many examples in the documentation when (after installing the library) you drag the library folder into your Opusmodus project navigator and open the documentation within Opusmodus.

NOTE: Unfortunately, evaluating code from within HTML files is currently broken in Opusmodus. (As is some HTML navigation that worked in previous Opusmodus versions.)

Evaluating code from in PDF files is working, though, so you can currently at least execute examples in the PDF version of the TOT tutorial directly from within Opusmodus. The TOT reference is only available in HTML format, though.

Installation

The instructions below use git for the installation. Even though it is a bit more involved at first, it allows for convenient updates later, and you can even contribute to the development.

Install git (if you have not done already). Also, you should register at GitHub.

Download the present software with git into a directory where ASDF can find the software, e.g., ~/common-lisp/. For example, on UNIX incl. OS X you can enter the following commands at the command line (after you created the directory ~/common-lisp/). Note that $ is the terminal prompt here, you do not need to enter that :)

$ cd ~/common-lisp
$ git clone https://github.com/tanders/tot.git

You might be be asked for your GitHub username and password.

This library depends on several other libraries. You can download the library cl-utilities at this link. You can install it by copying the unpacked directory into your local directory ~/common-lisp/ as well.

Other libraries you can install in the same way as TOT itself.

$ cd ~/common-lisp
$ git clone https://github.com/tanders/string-tools.git
$ git clone https://github.com/tanders/ta-utilities.git
$ git clone https://github.com/tanders/fenv.git
$ git clone https://github.com/tanders/cluster-engine.git 
$ git clone https://github.com/tanders/cluster-rules.git

A few functions depend on the MiniZinc (a constraint modelling language) to be installed, and the minizinc binary should be in your PATH.

Updating your software

If there are changes, you can update your software later at the terminal in the following way.

$ cd ~/common-lisp/tot
$ git pull

Make sure you update the dependencies likewise.

$ cd ~/common-lisp/string-tools
$ git pull
$ cd ~/common-lisp/ta-utilities
$ git pull
$ cd ~/common-lisp/fenv
$ git pull
$ cd ~/common-lisp/cluster-engine
$ git pull
$ cd ~/common-lisp/cluster-rules
$ git pull

Usage

This library is an ASDF system (ASDF is the de facto standard for building Common Lisp software), and you can load it into Opusmodus by evaluating the following line (e.g., make it part the code of your Opusmodus project). All dependency libraries are loaded automatically as well. The first time you do this, your Lisp compiler will show you a long list of compilation messages including various warnings, which you can savely ignore. Afterwards, you are ready to use whatever function etc. you want from this library (and its dependencies).

;; How to load in Opusmodus 3
(asdf:load-system :tot)

;; Loadiing in Opusmodus 2
(require :tot)

As already mentioned, for most convenient use within Opusmodus, you can drag and drop the whole folder of this library in the browser of an Opusmodus project. Then, visit the HTML documentation of this library from within Opusmodus: open the tot folder, and then its contained folder docs and click on an HTML file, say index.html. You can now browse the reference documentation of the library within Opusmodus, which explains its individual definitions. Most importantly, you can directly run all example code in the documentation from within Opusmodus (thanks, Janusz Podrazik).

This collection of definitions is roughly sorted in the file structure and documentation according to certain musical aspects (rhythm, pitches, musical form…).

Note that dependencies of this library are of interest on their own for computer-aided composition. This is particularly true for the constraint library cluster engine and its extension cluster rules, as well as the library fenv.

License

Distributed under the GNU General Public License.

Copyright © 2018, 2019, 2021 Torsten Anders