first push from separate repo

.gitattributes

@@ -0,0 +1,5 @@
+*.js binary
+*.woff binary
+*.html binary
+*.json binary
+*.css binary

.gitignore

@@ -0,0 +1,4 @@
+.Rproj.user
+.Rhistory
+.RData
+.Ruserdata

CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who 
+contribute through reporting issues, posting feature requests, updating documentation,
+submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for
+everyone, regardless of level of experience, gender, gender identity and expression,
+sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or
+imagery, derogatory comments or personal attacks, trolling, public or private harassment,
+insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments,
+commits, code, wiki edits, issues, and other contributions that are not aligned to this 
+Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed 
+from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by 
+opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the Contributor Covenant 
+(http:contributor-covenant.org), version 1.0.0, available at 
+http://contributor-covenant.org/version/1/0/0/

CONTRIBUTING.md

@@ -0,0 +1,9 @@
+Contributing to the project is really quite simple:
+
+1. Read the code of conduct at <https://github.com/AlgoCompSynth/CLAMS-doc/blob/master/CODE_OF_CONDUCT.md>.
+2. Everything starts with an issue. See [Always start with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/) for the philosophy.
+    * Is the documentation unclear? [File an issue](https://github.com/AlgoCompSynth/CLAMS-doc/issues/new).
+    * Did you find a bug? [File an issue](https://github.com/AlgoCompSynth/CLAMS-doc/issues/new).
+    * Do you want to request a feature? [File an issue](https://github.com/AlgoCompSynth/CLAMS-doc/issues/new).
+
+*Please, don't go through the mechanics of forking / pull requests even for trivial typo changes without filing an issue. [File an issue](https://github.com/AlgoCompSynth/CLAMS-doc/issues/new).*

The-Book-of-CLAMS/.gitignore

@@ -0,0 +1,2 @@
+/.quarto/
+.RData

The-Book-of-CLAMS/About-My-Music.qmd

@@ -0,0 +1,62 @@
+# About My Music
+
+> "Markovs of the world unite! You have nothing to lose but your chains!"
+\~ M. Edward (Ed) Borasky
+
+## AlgoCompSynth
+"AlgoCompSynth" is a word I made up to describe what it is that I want to do.
+It's a compression of "algorithmic composition and digital sound synthesis."
+That's a pretty broad class of music; to narrow it down, the following are my
+main inspirations.
+
+- Iannis Xenakis' _Formalized Music_ [@xenakis1992formalized]. Xenakis took the
+applied mathematics of his day, for example, operations research and game
+theory, and used these algorithms to create scores for conventional and
+electronic performers. He also invented a technique called "Dynamic
+Stochastic Synthesis", which uses Markov processes to specify not just the
+score of a piece but the parameters of the sound waveforms
+[@hoffmann1996implementing; @brown2005extending; @xenakis1992formalized].
+
+- Alternate tunings. Primary among these is William Sethares' _Tuning, Timbre
+Spectrum, Scale_ [@sethares1998tuning; @sethares2013tuning]. Also influential:
+Wendy Carlos [@carlos1987tuning], Harry Partch [@partch1979genesis], Erv
+Wilson [@narushima2019microtonality] and Nick Collins [@collins2008errant;
+@collins2012even].
+
+- Physical modeling synthesis. A comprehensive reference can be found at
+[@paspweb2010].
+
+- Spectral music. This is another advanced synthesis methodology; a recent
+reference is [@lazzarini2021spectral]
+
+My current home for published music is on Bandcamp at
+<https://algocompsynth.bandcamp.com/>. I may move to Gumroad, which allows
+publishing a broader range of digital media artefacts than music and music
+videos.
+
+## Other AlgoCompSynth projects
+
+1. [AlgoCompSynth-One](https://github.com/AlgoCompSynth/AlgoCompSynth-One):
+This is a platform for doing high-performance digital signal processing and
+musical AI on NVIDIA GPUs. I currently support Windows 11 WSL Ubuntu 22.04 LTS
+and NVIDIA Jetson JetPack 5.
+
+    If I can make everything work I will be supporting native Windows 11.
+    `AlgoCompSynth-One` is based on
+    [Mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html),
+    and Mamba runs on Windows, so unless other dependencies can't be found, it
+    should be possible.
+
+2. [eikosany](https://algocompsynth.github.io/eikosany/): This is an R
+package for algorithmic composition with musical scales derived by Erv Wilson
+and students of his theories.
+
+3. [consonaR](https://algocompsynth.github.io/consonaR/): This is an R
+package to perform the computations described in _Tuning, Timbre, Spectrum,
+Scale_ [@sethares2013tuning]. This is a superset of any such algorithms that
+will be deployed in CLAMS; only calculations that need to be performed
+during a performance need to be deployed in CLAMS.
+
+There is a fairly large overlap in functionality between `eikosany` and
+`consonaR`. There's a plan for refactoring the two, but that work is on hold
+until I get more of `CLAMS` done.

The-Book-of-CLAMS/CLAMS-Forth-Overview.qmd

@@ -0,0 +1,106 @@
+# CLAMS-Forth Overview
+
+> "If you've seen one Forth, well, you've seen one Forth." ~ Unknown
+
+## Requirements
+
+1. Compatibility with the Raspberry Pi Pico C/C++ SDK, drivers, and
+libraries: The ability to use the massive toolset the SDK and community
+open source projects provide is absolutely crucial to minimize developer
+time for complex projects. The USB and WiFi / Bluetooth stacks alone would
+take many months to duplicate in Forth. The primary references for this
+are Stephen Smith's _RP2040 Assembly Language Programming_ [@smith2021rp2040],
+and, of course, _Raspberry Pi Pico C/C++ SDK_ [@raspberrypi2023a].
+
+2. Optimized for speed: CLAMS-Forth will be written in RP2040 assembly
+and will provide an RP2040 assembler.
+
+3. Digital signal processing: A high-speed block floating point digital signal processing library will be provided.
+
+## Desiderata
+
+1. Forth 2012 standard compatibility is a strong desire but not an absolute
+requirement. Much of the CORE word set and some of the CORE EXT word set
+will be implemented, but a number of tricky, risky or little-used CORE words
+will be omitted. Many of the two-cell operations, for example, aren't really
+needed in a Forth running on a 32-bit architecture like the RP2040.
+
+    Parts of the Search-Order and Programming-Tools word sets will be
+    implemented. I want to have the Block word set using blocks in flash memory,
+    but that's not going to be in the first release.
+
+    Custom word sets will be provided for high-speed digital signal processing
+    and SDK / hardware access. ***All access to the hardware / system level
+    operations will be performed via C language calls to the SDK.***
+
+2. Cooperative multitasking: The RP2040 has two cores, and each core has a
+divide coprocessor and two interpolators. In addition, the RP2040 has two
+programmable input / output (PIO) blocks. Cooperative multitasking is the Forth
+way to exploit this available concurrency and is well-supported by the SDK.
+
+3. Portability to other boards with the RP2040 microcontroller is possible,
+but is not on the roadmap yet. As with CLAMS itself, the initial target is the
+Pimoroni PicoVision.
+
+4. Floating point support is desirable, but is a fairly low priority. Floating
+point arithmetic is convenient, and the RP2040 SDK provides optimized floating
+point libraries, but there's no hardware floating point arithmetic on the
+RP2040. It's too slow for real-time digital signal processing, so it's not
+obvious how useful this capability would be.
+
+## Design / architecture
+
+The top-level design and architecture are based on Dr. Chen-Hanson Ting's
+_eForth Overview_ [@pintaske2018eforth]. In eForth, a small number of primitive
+words are implemented with a macro assembler, then the rest of the system is
+built in Forth on top of those words. Brad Rodriguez' CamelForth
+[@pintaske2018moving] also provides some implementation guidance.
+
+The original plan for CLAMS-Forth was to use subroutine threading and inline
+code. There is a partial implementation, but I decided to switch to a more
+"traditional" but less efficient direct threaded implementation. There are two
+main reasons:
+
+1. The branch instructions in the RP2040 are program counter relative, and the
+available target distances are limited by the instruction formats. In particular,
+the function call (`BL`) instruction has an available range of plus or minus
+16 megabytes. While this is enough within the RP2040's flash or SRAM, it is
+*not* enough to cross the address space distance between SRAM and flash.
+
+    CLAMS-Forth will have a dictionary split between flash and SRAM. The entire
+    system dictionary - Forth virtual machine, text interpreter and compiler -
+    will be in flash. Only words created by the user at run time will be in
+    SRAM.
+
+    Dr. Ting's _eForth for Discovery_ [@pintaske2019irreducible] gets around
+    this limitation by copying the system dictionary from flash to RAM at boot
+    time. But the hardware he used has more RAM and a more complete instruction
+    set than the RP2040. The RP2040 only has 264 kilobytes of SRAM and much of
+    that will be used for audio buffers. The more code and tables safely stashed
+    away in the 2 megabytes of flash, the better.
+
+2. Even with a dictionary entirely in SRAM at run time, constructing a `BL`
+function call instruction while compiling a user "colon" definition is a tricky
+process, difficult to document, understand and maintain. If you're interested
+in the details, see [@pintaske2019irreducible, section 3.5.5 ]. I decided to
+switch to direct threading, rather than spend an extra week coding both a
+flash-to-SRAM relocation and an algorithm to compute a relative branch address
+that is then split into four separate bit fields of two 16-bit `thumb`
+instructions.
+
+## Status / roadmap
+
+1. There is a partial implementation of a subroutine-threaded version with
+inlining. I am leaving that in the repository in a development branch but won't
+be working on it unless I find that the direct-threaded version cannot meet
+speed requirements. The subroutine-threaded version is in branch
+[`forth-stc`](https://github.com/AlgoCompSynth/CLAMS/tree/forth-stc).
+
+2. The direct-threaded version is nearing a release. I expect to have the
+system dictionary, text interpreter and compiler done by January 1, 2024. It is
+in the branch
+[`forth-dtc`](https://github.com/AlgoCompSynth/CLAMS/tree/forth-stc).
+
+3. The next step is to implement synthesis algorithms. The general process will
+be to prototype them in Forth, converting to assembler when needed. That will
+create the requirements for the digital signal processing library.

The-Book-of-CLAMS/The-Book-of-CLAMS.Rproj

@@ -0,0 +1,13 @@
+Version: 1.0
+
+RestoreWorkspace: Default
+SaveWorkspace: Default
+AlwaysSaveHistory: Default
+
+EnableCodeIndexing: Yes
+UseSpacesForTab: Yes
+NumSpacesForTab: 2
+Encoding: UTF-8
+
+RnwWeave: knitr
+LaTeX: XeLaTeX

The-Book-of-CLAMS/_quarto.yml

@@ -0,0 +1,24 @@
+project:
+  type: book
+  output-dir: ../docs
+
+book:
+  title: "The Book of CLAMS"
+  author: "M. Edward (Ed) Borasky"
+  date: "12/15/2023"
+  chapters:
+    - index.qmd
+    - About-My-Music.qmd
+    - CLAMS-Forth-Overview.qmd
+    - references.qmd
+
+bibliography: references.bib
+
+format:
+  html:
+    theme: darkly
+  pdf:
+    documentclass: scrreprt
+
+
+

The-Book-of-CLAMS/index.qmd

@@ -0,0 +1,83 @@
+# Command Line Algorithmic Music System (CLAMS) {.unnumbered}
+
+> “I’ve never seen a happy clam. In fact, most of them were really
+> steamed.” ~ M. Edward (Ed) Borasky
+
+## Overview
+
+`CLAMS` is a text-based interactive environment for composing and performing
+music and visuals on a [Pimoroni
+PicoVision](https://shop.pimoroni.com/products/picovision?variant=41048911904851).
+It can be made to work on other boards using the RP2040 microcontroller, but
+you will need to buy additional hardware and port some code.
+
+## How does it work?
+
+`CLAMS` is a domain-specific language built on a Forth compiler /
+interpreter. The user connects to the board via a USB or UART serial connection
+and enters `CLAMS` / Forth code interactively.
+
+## Why Forth?
+
+1. Forth [@brodie2022] is an extensible interactive operating system. It
+supports editing, assembling, compiling, debugging and running real-time
+tasks from a terminal.
+2. Forth is efficient. A well-designed Forth will usually run a task at no
+worse than half the speed of a hand-optimized assembly version. `CLAMS` will
+have several optimizations built in for the ultimate speed.
+3. Forth is lean. There are very few concepts to learn, there is minimal
+run-time overhead in RAM, and the whole package takes up much less flash space
+than MicroPython or CircuitPython.
+
+## What about Forth standard [@forth2022] compatibility?
+
+`CLAMS` is an extended subset of the standard. It won't contain all of the
+standard's core word set, and it will contain some extensions to support
+the Raspberry Pi Pico C/C++ SDK, RP2040 assembly language programming, the
+PicoVision hardware, cooperative multitasking, and high-speed digital signal
+processing.
+
+## What about portability?
+
+Within the RP2040 ecosystem, as long as the PicoVision and C/C++ SDK work,
+porting should be straightforward, though tedious. And you will undoubtedly need
+to buy more hardware.
+
+Outside of the RP2040 ecosystem, there are a number of other micro-controller
+music boards, most notably the [Electro-Smith
+Daisy](https://www.electro-smith.com/daisy
+"Electro-Smith Daisy") and the [Rebel Technology
+OWL](https://github.com/RebelTechnology/OpenWare "Rebel Technology on
+GitHub") platforms. But they have their own SDKs, so there's not much need to
+port `CLAMS` to them.
+
+There are also a number of audio projects that use the [Teensy® USB Development
+Board](https://www.pjrc.com/teensy/ "Teensy Home Page"), which has a
+[comprehensive audio library](https://www.pjrc.com/teensy/td_libs_Audio.html
+"Teensy Audio Library"). Like the first two, it has its own SDK. And the Daisy,
+OWL and Teensy processors are all more powerful than the RP2040.
+
+By contrast, there's not much music-specific development software for the
+Raspberry Pi Pico / RP2040. There are some simple demos, a few do-it-yourself
+hardware offerings, and there's the
+[Allen Synthesis EuroPi](https://allensynthesis.co.uk/modules/europi.html
+"EuroPi module"), a Eurorack module with an open source MicroPython software
+platform. `CLAMS` will be a different approach.
+
+The overall concept is an interactive language for making music on Raspberry
+Pi Pico / RP2040. I'm aiming for [ChucK](https://chuck.stanford.edu/ "ChucK
+Home Page") [@salazar2014programming] semantics with Forth syntax - a single
+text-based language to implement both the definitions of synthesized
+instruments and the sequences of sounds they make, intended for [live coding
+/ algorave](https://github.com/toplap/awesome-livecoding "Awesome Live Coding
+list on GitHub") performances.
+
+* * * * *
+
+This is a Quarto book.
+
+To learn more about Quarto books visit <https://quarto.org/docs/books>.
+
+* * * * *
+
+ <p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://algocompsynth.github.io/CLAMS/">The Book of CLAMS</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://github.com/znmeb">M. Edward (Ed) Borasky</a> is marked with <a href="http://creativecommons.org/publicdomain/zero/1.0?ref=chooser-v1" target="_blank" rel="license noopener noreferrer" style="display:inline-block;">CC0 1.0 Universal<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1"><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/zero.svg?ref=chooser-v1"></a></p>