jjinx 0.0.1__tar.gz

jjinx-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Riley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jjinx-0.0.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: jjinx
+Version: 0.0.1
+Summary: Interpreter for the J programming language.
+Author: Alex Riley
+License: MIT License
+        
+        Copyright (c) 2025 Alex Riley
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/ajcr/jinx
+Keywords: J,interpreter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.3.3
+Dynamic: license-file
+
+# Jinx
+
+![ci](https://github.com/ajcr/jinx/actions/workflows/ci.yaml/badge.svg?branch=main)
+
+An experimental interpreter for the J programming language, built on top of [NumPy](https://numpy.org/).
+
+Implements many of J's primitives and tacit programming capabilities, and can be extended to support execution via other frameworks too.
+
+## Executing J
+
+Start the interactive shell:
+```sh
+jinx
+```
+The shell prompt is four spaces, so commands appear indented. Internally, all multidimensional arrays are NumPy arrays. Verbs, conjunctions and adverbs are a mixture of Python and NumPy methods.
+
+Here are some examples what Jinx can do so far:
+
+- Solve the "trapping rainwater" problem (solution taken from [here](https://mmapped.blog/posts/04-square-joy-trapped-rain-water)):
+```j
+    +/@((>./\ <. >./\.)-]) 0 1 0 2 1 0 1 3 2 1 2 1
+6
+```
+- Compute the correlation between two arrays of numbers (taken from [here](https://stackoverflow.com/a/44845495/3923281)). This is a complex combination of different verbs, adverbs, conjunctions and trains:
+```j
+    2 1 1 7 9 (+/@:* % *&(+/)&.:*:)&(- +/%#) 6 3 1 5 7
+0.721332
+```
+- Create identity matrices in inventive ways (see [this essay](https://code.jsoftware.com/wiki/Essays/Identity_Matrix)):
+```j
+    |.@~:\ @ ($&0) 3
+1 0 0
+0 1 0
+0 0 1
+
+    (i.@,~ = >: * i.) 3
+1 0 0
+0 1 0
+0 0 1
+
+    ((={:)\ @ i.) 3
+1 0 0
+0 1 0
+0 0 1
+```
+- Solve the Josephus problem (see [this essay](https://code.jsoftware.com/wiki/Essays/Josephus_Problem)). Calculate the survivor's number for a circle of people of size N. Note the use of verb obverse and the rank conjunction:
+```j
+    (1&|.&.#:)"0 >: i. 5 10    NB. N ranges from 1 to 50 here (arranged as a table)
+ 1  1  3  1  3  5  7  1  3  5
+ 7  9 11 13 15  1  3  5  7  9
+11 13 15 17 19 21 23 25 27 29
+31  1  3  5  7  9 11 13 15 17
+19 21 23 25 27 29 31 33 35 37
+```
+- Build nested boxes containing heterogeneous data types and print the contents:
+```j
+    (<<'abc'),(<(<'de',.'fg'),(<<i. 5 2)),(<(<"0 ] % i. 2 2 3))
+┌─────┬──────────┬────────────────────────────┐
+│┌───┐│┌──┬─────┐│┌────────┬────────┬────────┐│
+││abc│││df│┌───┐│││_       │1       │0.5     ││
+│└───┘││eg││0 1│││├────────┼────────┼────────┤│
+│     ││  ││2 3││││0.333333│0.25    │0.2     ││
+│     ││  ││4 5│││└────────┴────────┴────────┘│
+│     ││  ││6 7│││                            │
+│     ││  ││8 9│││┌────────┬────────┬────────┐│
+│     ││  │└───┘│││0.166667│0.142857│0.125   ││
+│     │└──┴─────┘│├────────┼────────┼────────┤│
+│     │          ││0.111111│0.1     │0.090909││
+│     │          │└────────┴────────┴────────┘│
+└─────┴──────────┴────────────────────────────┘
+```
+
+## Easily Customisable
+
+Everything is in Python. Adding new primitives is easy.
+
+Update the `primitives.py` file with your new part of speech (e.g. a new verb such as `+::`). Write your implementation of this new part of speech in the relevant executor module (e.g. `verbs.py`) and then update the name-to-method mapping at the foot of that module. That's all that's needed.
+
+## Alternative Executors
+
+Execution of sentences is backed by NumPy by default.
+
+However Jinx is designed so that it's possible to implement the primitives using alternative frameworks too. Python many Machine Learning and Scientific Programming libraries that could be used to execution J code.
+
+To prove this concept, there's _highly experimental and incomplete_ support for [JAX](https://docs.jax.dev/en/latest/index.html):
+```sh
+jinx --executor jax
+```
+Primitive verbs are JIT compiled and execute on JAX arrays:
+```j
+    mean =: +/ % #
+    mean 33 55 77 100 101
+73.2
+```
+
+## Warning
+
+This project is experimental. There will be bugs, missing features and performance quirks.
+
+Many key parts of J are not currently implemented (but might be in future). These include:
+- Differences in how names are interpreted and resolved at execution time.
+- Locales.
+- Definitions and direct definitions (using `{{ ... }}`).
+- Array types other than floats, integers and and strings.
+- Executing J scripts.
+- Control words.

jjinx-0.0.1/README.md

@@ -0,0 +1,106 @@
+# Jinx
+
+![ci](https://github.com/ajcr/jinx/actions/workflows/ci.yaml/badge.svg?branch=main)
+
+An experimental interpreter for the J programming language, built on top of [NumPy](https://numpy.org/).
+
+Implements many of J's primitives and tacit programming capabilities, and can be extended to support execution via other frameworks too.
+
+## Executing J
+
+Start the interactive shell:
+```sh
+jinx
+```
+The shell prompt is four spaces, so commands appear indented. Internally, all multidimensional arrays are NumPy arrays. Verbs, conjunctions and adverbs are a mixture of Python and NumPy methods.
+
+Here are some examples what Jinx can do so far:
+
+- Solve the "trapping rainwater" problem (solution taken from [here](https://mmapped.blog/posts/04-square-joy-trapped-rain-water)):
+```j
+    +/@((>./\ <. >./\.)-]) 0 1 0 2 1 0 1 3 2 1 2 1
+6
+```
+- Compute the correlation between two arrays of numbers (taken from [here](https://stackoverflow.com/a/44845495/3923281)). This is a complex combination of different verbs, adverbs, conjunctions and trains:
+```j
+    2 1 1 7 9 (+/@:* % *&(+/)&.:*:)&(- +/%#) 6 3 1 5 7
+0.721332
+```
+- Create identity matrices in inventive ways (see [this essay](https://code.jsoftware.com/wiki/Essays/Identity_Matrix)):
+```j
+    |.@~:\ @ ($&0) 3
+1 0 0
+0 1 0
+0 0 1
+
+    (i.@,~ = >: * i.) 3
+1 0 0
+0 1 0
+0 0 1
+
+    ((={:)\ @ i.) 3
+1 0 0
+0 1 0
+0 0 1
+```
+- Solve the Josephus problem (see [this essay](https://code.jsoftware.com/wiki/Essays/Josephus_Problem)). Calculate the survivor's number for a circle of people of size N. Note the use of verb obverse and the rank conjunction:
+```j
+    (1&|.&.#:)"0 >: i. 5 10    NB. N ranges from 1 to 50 here (arranged as a table)
+ 1  1  3  1  3  5  7  1  3  5
+ 7  9 11 13 15  1  3  5  7  9
+11 13 15 17 19 21 23 25 27 29
+31  1  3  5  7  9 11 13 15 17
+19 21 23 25 27 29 31 33 35 37
+```
+- Build nested boxes containing heterogeneous data types and print the contents:
+```j
+    (<<'abc'),(<(<'de',.'fg'),(<<i. 5 2)),(<(<"0 ] % i. 2 2 3))
+┌─────┬──────────┬────────────────────────────┐
+│┌───┐│┌──┬─────┐│┌────────┬────────┬────────┐│
+││abc│││df│┌───┐│││_       │1       │0.5     ││
+│└───┘││eg││0 1│││├────────┼────────┼────────┤│
+│     ││  ││2 3││││0.333333│0.25    │0.2     ││
+│     ││  ││4 5│││└────────┴────────┴────────┘│
+│     ││  ││6 7│││                            │
+│     ││  ││8 9│││┌────────┬────────┬────────┐│
+│     ││  │└───┘│││0.166667│0.142857│0.125   ││
+│     │└──┴─────┘│├────────┼────────┼────────┤│
+│     │          ││0.111111│0.1     │0.090909││
+│     │          │└────────┴────────┴────────┘│
+└─────┴──────────┴────────────────────────────┘
+```
+
+## Easily Customisable
+
+Everything is in Python. Adding new primitives is easy.
+
+Update the `primitives.py` file with your new part of speech (e.g. a new verb such as `+::`). Write your implementation of this new part of speech in the relevant executor module (e.g. `verbs.py`) and then update the name-to-method mapping at the foot of that module. That's all that's needed.
+
+## Alternative Executors
+
+Execution of sentences is backed by NumPy by default.
+
+However Jinx is designed so that it's possible to implement the primitives using alternative frameworks too. Python many Machine Learning and Scientific Programming libraries that could be used to execution J code.
+
+To prove this concept, there's _highly experimental and incomplete_ support for [JAX](https://docs.jax.dev/en/latest/index.html):
+```sh
+jinx --executor jax
+```
+Primitive verbs are JIT compiled and execute on JAX arrays:
+```j
+    mean =: +/ % #
+    mean 33 55 77 100 101
+73.2
+```
+
+## Warning
+
+This project is experimental. There will be bugs, missing features and performance quirks.
+
+Many key parts of J are not currently implemented (but might be in future). These include:
+- Differences in how names are interpreted and resolved at execution time.
+- Locales.
+- Definitions and direct definitions (using `{{ ... }}`).
+- Array types other than floats, integers and and strings.
+- Executing J scripts.
+- Control words.

jjinx-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires      = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jjinx"
+version = "0.0.1"
+description = "Interpreter for the J programming language."
+readme = "README.md"
+authors = [{ name = "Alex Riley" }]
+license = { file = "LICENSE" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+]
+keywords = ["J", "interpreter"]
+requires-python = ">=3.13"
+dependencies = [
+    "numpy>=2.3.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/ajcr/jinx"
+
+[project.scripts]
+jinx = "jinx.shell:main"
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src"
+]
+addopts = [
+    "--import-mode=importlib",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.18.2",
+    "pytest>=8.4.2",
+    "ruff>=0.13.1",
+]
+jax = [
+    "jax>=0.7.2",
+]

jjinx-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jjinx-0.0.1/src/jinx/errors.py

@@ -0,0 +1,41 @@
+"""J errors for incorrect usage of J primitives."""
+
+
+class BaseJError(Exception):
+    pass
+
+
+class LengthError(BaseJError):
+    pass
+
+
+class DomainError(BaseJError):
+    pass
+
+
+class ValenceError(BaseJError):
+    pass
+
+
+class JIndexError(BaseJError):
+    pass
+
+
+class SpellingError(BaseJError):
+    pass
+
+
+class StackError(BaseJError):
+    pass
+
+
+class EvaluationError(BaseJError):
+    pass
+
+
+class JSyntaxError(BaseJError):
+    pass
+
+
+class JinxNotImplementedError(BaseJError):
+    """Raised when a feature is not implemented in Jinx."""

jjinx-0.0.1/src/jinx/execution/executor.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass
+from typing import Callable
+
+from jinx.vocabulary import Adverb, Conjunction, Noun, Verb
+
+
+@dataclass(frozen=True)
+class Executor[T]:
+    apply_monad: Callable[[Verb[T], Noun[T]], Noun[T]]
+    """Apply monadic form of verb to a noun."""
+
+    apply_dyad: Callable[[Verb[T], Noun[T], Noun[T]], Noun[T]]
+    """Apply dyadic form of verb to two nouns."""
+
+    apply_conjunction: Callable[
+        [Verb[T] | Noun[T], Conjunction, Verb[T]], Verb[T] | Noun[T]
+    ]
+    """Apply conjunction to left and right arguments."""
+
+    apply_adverb: Callable[[Verb[T] | Noun[T], Adverb], Verb[T] | Noun[T]]
+    """Apply adverb to left argument."""
+
+    build_fork: Callable[[Noun[T] | Verb[T], Verb[T], Verb[T]], Verb[T]]
+    """Build fork."""
+
+    build_hook: Callable[[Verb[T], Verb[T]], Verb[T]]
+    """Build hook."""
+
+    ensure_noun_implementation: Callable[[Noun[T]], None]
+    """Ensure that the noun has an implementation."""
+
+    primitive_verb_map: dict[
+        str, tuple[Callable[[T], T] | None, Callable[[T, T], T] | None]
+    ]
+    """Map of primitive verb names to implementations of monad and dyad functions."""
+
+    primitive_adverb_map: dict[str, Callable[[Verb[T]], Verb[T]]]
+    """Map of primitive adverb names to implementation function."""
+
+    primitive_conjuction_map: dict[
+        str, Callable[[Verb[T] | Noun[T], Verb[T] | Noun[T]], Verb[T]]
+    ]
+    """Map of primitive conjunction names to implementation function."""
+
+    noun_to_string: Callable[[Noun[T]], str]
+    """Convert a noun to a string representation for printing."""
+
+
+def load_executor(name: str) -> Executor:
+    if name == "numpy":
+        from jinx.execution.numpy import executor as numpy_executor
+
+        return numpy_executor
+
+    if name == "jax":
+        from jinx.execution.jax import executor as jax_executor
+
+        return jax_executor
+
+    raise ValueError(f"Unknown executor: {name}")

jjinx-0.0.1/src/jinx/execution/jax/__init__.py

@@ -0,0 +1,45 @@
+import jax
+from jinx.errors import JinxNotImplementedError
+from jinx.execution.executor import Executor
+from jinx.execution.jax.adverbs import ADVERB_MAP
+from jinx.execution.jax.application import (
+    apply_adverb,
+    #     apply_conjunction,
+    apply_dyad,
+    apply_monad,
+    build_fork,
+    #     build_hook,
+    ensure_noun_implementation,
+)
+from jinx.execution.jax.verbs import VERB_MAP
+
+# from jinx.execution.numpy.conjunctions import CONJUNCTION_MAP
+# from jinx.execution.numpy.conversion import ensure_noun_implementation
+from jinx.execution.numpy.printing import noun_to_string
+
+jax.config.update("jax_dynamic_shapes", True)
+
+
+def make_not_implemented(name: str):
+    def _not_implemented(*_, **__):
+        raise JinxNotImplementedError(
+            f"{name}: not yet implemented in the JAX executor."
+        )
+
+    return _not_implemented
+
+
+executor = Executor[jax.Array](
+    apply_monad=apply_monad,
+    apply_dyad=apply_dyad,
+    apply_conjunction=make_not_implemented("conjunction"),
+    apply_adverb=apply_adverb,
+    build_fork=build_fork,
+    build_hook=make_not_implemented("hook"),
+    ensure_noun_implementation=ensure_noun_implementation,
+    primitive_verb_map=VERB_MAP,
+    primitive_adverb_map=ADVERB_MAP,
+    primitive_conjuction_map={},
+    # Just use the NumPy implementation of printing.
+    noun_to_string=noun_to_string,  # type: ignore[arg-type]
+)

jjinx-0.0.1/src/jinx/execution/jax/adverbs.py

@@ -0,0 +1,91 @@
+"""Methods implementing J adverbs."""
+
+import functools
+from typing import Callable
+
+import jax
+import jax.numpy as jnp
+from jinx.errors import JinxNotImplementedError, ValenceError
+from jinx.execution.jax.application import _apply_dyad
+from jinx.execution.numpy.helpers import (
+    maybe_parenthesise_verb_spelling,
+)
+from jinx.vocabulary import Dyad, Monad, Verb
+
+INFINITY = float("inf")
+
+
+def slash_adverb(verb: Verb[jax.Array]) -> Verb[jax.Array]:
+    if verb.dyad is None or verb.dyad.function is None:
+        # Note: this differs from J which still allows the adverb to be applied
+        # to a verb, but may raise an error when the new verb is applied to a noun
+        # and the verb has no dyadic valence.
+        raise ValenceError(f"Verb {verb.spelling} has no dyadic valence.")
+
+    if isinstance(verb.dyad.function, jnp.ufunc) and verb.dyad.is_commutative:
+        monad = verb.dyad.function.reduce
+        dyad = verb.dyad.function.outer
+
+    else:
+        # Slow path: dyad is not a ufunc.
+        # The function is either callable, in which cases it is applied directly,
+        # or a Verb object that needs to be applied indirectly with _apply_dyad().
+        if isinstance(verb.dyad.function, Verb):
+            func = functools.partial(_apply_dyad, verb)  # type: ignore[assignment]
+        else:
+            func = verb.dyad.function  # type: ignore[assignment]
+
+        def _dyad_arg_swap(x: jax.Array, y: jax.Array) -> jax.Array:
+            return func(y, x)
+
+        def _reduce(y: jax.Array) -> jax.Array:
+            y = jnp.atleast_1d(y)
+            y = jnp.flip(y, axis=0)
+            return functools.reduce(_dyad_arg_swap, y)
+
+        monad = _reduce  # type: ignore[assignment]
+        dyad = NotImplemented
+
+    spelling = maybe_parenthesise_verb_spelling(verb.spelling)
+    spelling = f"{verb.spelling}/"
+
+    return Verb[jax.Array](
+        name=spelling,
+        spelling=spelling,
+        monad=Monad(name=spelling, rank=INFINITY, function=monad),
+        dyad=Dyad(
+            name=spelling, left_rank=INFINITY, right_rank=INFINITY, function=dyad
+        ),
+    )
+
+
+def bslash_adverb(verb: Verb[jax.Array]) -> Verb[jax.Array]:
+    # Common cases that have a straightforward optimisation.
+    SPECIAL_MONAD = {
+        "+/": jnp.cumulative_sum,
+        "*/": jnp.cumulative_prod,
+    }
+
+    if verb.spelling in SPECIAL_MONAD:
+        monad_ = SPECIAL_MONAD[verb.spelling]
+
+    else:
+        raise JinxNotImplementedError(
+            f"Adverb \\ applied to verb {verb.spelling} is not yet implemented."
+        )
+
+    spelling = maybe_parenthesise_verb_spelling(verb.spelling)
+    spelling = f"{spelling}\\"
+
+    return Verb(
+        name=spelling,
+        spelling=spelling,
+        monad=Monad(name=spelling, rank=INFINITY, function=monad_),
+        dyad=Dyad(name=spelling, left_rank=0, right_rank=INFINITY, function=None),  # type: ignore[arg-type]
+    )
+
+
+ADVERB_MAP: dict[str, Callable[[Verb[jax.Array]], Verb[jax.Array]]] = {
+    "SLASH": slash_adverb,
+    "BSLASH": bslash_adverb,
+}