docs and compatibility

Author: ckrause

README.md

@@ -1,10 +1,17 @@
-# LODA Python Module
+# LODA Python
 
-This Python module contains an implementation of the [LODA Language](https://loda-lang.org/). You can use it to read, write and evaluate LODA programs to integer sequences, and to use machine learning to find new programs.
+This Python package contains an implementation of the [LODA Language](https://loda-lang.org/):
+an assembly language and computational model for finding integer sequence programs.
+
+This Python package allows you to read and write LODA programs, to evaluate
+them to integer sequences, to search for matches in the
+[OEIS](https://www.oeis.org/) database,
+and to use machine learning tools from [Tensorflow](https://www.tensorflow.org/)
+to find new integer sequence programs.
 
 ## Getting Started
 
-Install the dependencies for the LODA Python module:
+You need Python 3.7 or higher. To install the dependencies for LODA, run these commands:
 
 ```bash
 python3 -m venv env
@@ -18,4 +25,4 @@ To execute the tests, run the following command:
 nose2 tests -v
 ```
 
-Check out [sample.py](sample.py) and the [documentation](https://loda-lang.org/loda-python/) to find out how to use the LODA Python module.
+Check out [sample.py](sample.py) and the [documentation](https://loda-lang.org/loda-python/) to find out how to use the LODA Python package.

fibonacci.asm

@@ -0,0 +1,9 @@
+; A000045: Fibonacci numbers.
+mov $3,1
+lpb $0
+  sub $0,1
+  mov $2,$1
+  add $1,$3
+  mov $3,$2
+lpe
+mov $0,$1

loda/__init__.py

@@ -1,9 +1,6 @@
-"""Python implementation of the [LODA Language](https://loda-lang.org/):
-an assembly language and computational model for finding integer sequence programs.
+"""
+Python implementation of the [LODA Language](https://loda-lang.org/):
+an assembly language and computational model for integer sequences.
 
-This Python package allows you to read and write LODA programs, to evaluate
-them to integer sequences, to search for matches in the
-[On-Line Encyclopedia of Integer Sequences®](https://www.oeis.org/) (OEIS®),
-and to use machine learning from [Tensorflow](https://www.tensorflow.org/)
-to find new integer sequence programs.
+.. include:: ./documentation.md
 """

loda/documentation.md

@@ -0,0 +1,42 @@
+This Python package allows you to read and write LODA programs, to evaluate
+them to integer sequences, to search for matches in the
+[OEIS](https://www.oeis.org/) database,
+and to use machine learning from [Tensorflow](https://www.tensorflow.org/)
+to generate new integer sequence programs.
+
+## Installation
+
+You need Python 3.7 or higher. To install the dependencies for LODA, run these commands:
+
+```bash
+python3 -m venv env
+source env/bin/activate
+pip install -r requirements.txt
+```
+
+## Getting Started
+
+LODA programs are stored in `*.asm` files. Below you can find the example program `fibonacci.asm` which
+computes the Fibonacci numbers. For a comprehensive overview of the language, see the [LODA Language Specification](https://loda-lang.org/spec/).
+
+```asm
+; A000045: Fibonacci numbers.
+mov $3,1
+lpb $0
+  sub $0,1
+  mov $2,$1
+  add $1,$3
+  mov $3,$2
+lpe
+mov $0,$1
+```
+
+Check out the [sub-modules](#header-submodules) for working with LODA programs.
+
+## Development
+
+To execute the tests, run the following command:
+
+```bash
+nose2 tests -v
+```

loda/lang/__init__.py

@@ -1,4 +1,18 @@
-"""LODA Language core. Model and (de-)serialization of programs.
+"""
+Load and save programs.
+
+This module contains the in-memory representation of LODA programs. You can use it to load and save programs,
+and to inspect and manipulate their structure programmatically. You can load a program from an `*.asm` file
+as follows:
+
+>>> from loda.lang import Program
+>>>
+>>> with open("fibonacci.asm", "r") as file:
+>>>     program = Program(file.read())
+>>>     print(program)
+
+To save it, just write the string representation of the program to another file.
+To inspect and manipulate programs, see the `loda.lang.program.Program` class.
 """
 
 from .operand import Operand

loda/lang/operand.py

@@ -1,11 +1,12 @@
 # -*- coding: utf-8 -*-
 
+"""Operand model and serialization."""
+
 from enum import Enum
 
 
 class Operand:
-    """Operand model and (de-)serialization.
-
+    """
     Operands consist of two members: `type` (enum) and `value` (int).
     The operand's type can be either `CONSTANT`, `DIRECT` memory access,
     or `INDIRECT` memory access. Constants are plain integers. Direct

loda/lang/operation.py

@@ -1,12 +1,13 @@
 # -*- coding: utf-8 -*-
 
+"""Operation model and serialization."""
+
 from enum import Enum
 from .operand import Operand
 
 
 class Operation:
-    """Operation model and (de-)serialization.
-
+    """
     Operations have the following structure: `<type> <target>,<source> ; <comment>`
     where the operation type is an enum consisting of three-letter operation names, and
     target and source are `loda.lang.operand.Operand`s. Depending on their type, 

loda/lang/program.py

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
 
+"""Program model and serialization."""
+
 from .operation import Operation
 
 
 class Program:
-    """Program model and (de-)serialization.
+    """
+    Programs are essentially a list of `Operation`s.
 
     >>> # Constructing programs from operations:
     >>> p1 = Program()
@@ -21,7 +24,7 @@ class Program:
     div $0,$2
     """
 
-    operations: list[Operation]
+    operations: list
     """Operations of this program."""
 
     def __init__(self, program_str=None):

loda/ml/__init__.py

@@ -1 +1,3 @@
-"""Machine learning integration for LODA using Tensorflow/Keras."""
+"""
+Machine learning integration.
+"""

loda/ml/keras.py

@@ -9,7 +9,7 @@
 
 class Model(tf.keras.Model):
 
-    def __init__(self, vocabulary: list[str],
+    def __init__(self, vocabulary: list,
                  embedding_dim: int = 256, num_rnn_units: int = 1024):
 
         super().__init__(self)
@@ -75,10 +75,10 @@ def __init__(self, model: Model, temperature: float = 1.0):
             dense_shape=[model.get_vocab_size()])
         self.prediction_mask = tf.sparse.to_dense(sparse_mask)
 
-    def ids_to_tokens_str(self, ids) -> list[str]:
+    def ids_to_tokens_str(self, ids) -> list:
         return [t.numpy().decode("utf-8") for t in self.model.ids_to_tokens(ids)]
 
-    def ids_to_programs(self, ids) -> list[Program]:
+    def ids_to_programs(self, ids) -> list:
         return util.split_program(util.tokens_to_program(self.ids_to_tokens_str(ids)))
 
     def program_to_input_ids(self, program: Program, num_lanes: int = 1):

loda/ml/util.py

@@ -1,11 +1,10 @@
 from loda.lang import Operand, Operation, Program
 from loda.oeis import ProgramCache
 
-import typing
 import random
 
 
-def program_to_tokens(program: Program) -> typing.Tuple[list[str], list[str]]:
+def program_to_tokens(program: Program):
     tokens = []
     vocab = set()
     for op in program.operations:
@@ -18,7 +17,7 @@ def program_to_tokens(program: Program) -> typing.Tuple[list[str], list[str]]:
         vocab.add(type)
         vocab.add(target)
         vocab.add(source)
-    return (tokens, sorted(vocab))
+    return tokens, sorted(vocab)
 
 
 def tokens_to_operation(type_tok: str, target_tok: str, source_tok: str):
@@ -31,7 +30,7 @@ def tokens_to_operation(type_tok: str, target_tok: str, source_tok: str):
         return Operation()  # nop
 
 
-def tokens_to_program(tokens: list[str]) -> Program:
+def tokens_to_program(tokens: list) -> Program:
     i = 0
     program = Program()
     while i+2 < len(tokens):
@@ -90,7 +89,7 @@ def merge_programs(program_cache: ProgramCache, num_programs: int = -1, num_ops_
     return merged, num_samples, sample_size
 
 
-def split_program(program: Program) -> list[Program]:
+def split_program(program: Program) -> list:
     splitted = []
     next = Program()
     for op in program.operations:

loda/oeis/__init__.py

@@ -1,6 +1,7 @@
 """
-Search integer sequences from the
-[On-Line Encyclopedia of Integer Sequences®](https://www.oeis.org/) (OEIS®).
+[OEIS](https://www.oeis.org/) integration.
+
+This module contains and integration with the [On-Line Encyclopedia of Integer Sequences®](https://www.oeis.org/).
 """
 
 from .prefix_index import PrefixIndex

loda/oeis/prefix_index.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+"""Prefix index for searching integer sequences."""
+
 import copy
 import os.path
 import re
@@ -105,7 +107,7 @@ def refine_match(self, match: Match, term: int) -> bool:
         match.end_index = new_end
         return new_start < new_end
 
-    def get_match_ids(self, match: Match) -> list[int]:
+    def get_match_ids(self, match: Match) -> list:
         ids = [self.__index[i].id for i in range(
             match.start_index, match.end_index)]
         ids.extend(match.finished_ids)

loda/oeis/program_cache.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+"""Program cache for integer sequence programs."""
+
 import os.path
 
 from loda.lang import Program

loda/oeis/sequence.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+"""Integer sequence model."""
+
 import functools
 
 

loda/runtime/__init__.py

@@ -1,4 +1,8 @@
-"""Runtime of the LODA language. Includes an interpreter for evaluating programs."""
+"""
+Evaluate programs to integer sequences.
+
+.. include:: ./documentation.md
+"""
 
 from .interpreter import Interpreter
 from .operations import *

loda/runtime/documentation.md

@@ -0,0 +1,17 @@
+You can evaluate LODA programs to an integer sequence as follows:
+
+```python
+from loda.lang import Program
+from loda.runtime import Interpreter
+
+with open("fibonacci.asm", "r") as file:
+    program = Program(file.read())
+    interpreter = Interpreter()
+    print(interpreter.eval_to_seq(program, num_terms=10))
+```
+
+The result is a pair, where the first entry is the list of computed Fibonacci numbers:
+
+```python
+([0, 1, 1, 2, 3, 5, 8, 13, 21, 34], 305)
+```