inconvergent/cl-veq

DSL and utilities for vector mathematics in Common Lisp

VEQ

VEQ is a DSL and a set of utilities for doing dealing with (primarily) 1d/2d/3d/nd point vectors and arrays of point vectors. It includes some geometry utilities like intersection tests, and other things related to graphics programming.

VEQ was written to be the vector library used in my generative art library auxin, and in cl-grph.

Examples and Documentation

Here are some examples of use:

(in-package :veq)

; fvprogn is a compiler for the veq DSL, and and environment that cointains
; many of the vector tools. among other things it handles the !@ triggers for
; common nd point vector operations such as f2!@+ for 2d single float point
; vector addition, and so on

; see [docs](DOCS.md) for vv macro for more info about !@, _@, .@ compiler
; and other triggers. the documentations also contains an automatically
; generated symbol documentation.

; here are some examples:

(fvprogn
  ; xlet makes it convenient to declare typed value packs ("veqs") with the
  ; trigger [t][d]![var], eg. f2!varname. the variable will the be replaced by
  ; the n values inside the scope.
  (xlet ((f2!a (f2 1 2))                                      ; (values 1f0 2f0)
         (f3!varname 0)                                       ; (values 0.0 0.0 0.0)
         (f2!b (f2 3 100))                                    ; (values 3f0 100f0)
         (line (f2$line 3f0 40f0 7f0 3f0))                    ; #(3f0 40f0 7f0 3f0)
         (xx :s)                                              ; just :s, as you expect
         (i3!integervar) (values 1 7 3)                       ; (values 1 7 3)
         (va (f$_ (loop for v from 0 below 6                  ; #(0.0 1.0 1.0
                        collect (list (ff v) (ff (1+ v))))))) ;   2.0 2.0 3.0
                                                              ;   3.0 4.0 4.0
                                                              ;   5.0 5.0 6.0)
    ; vp pretty prints input code and output values
    (vp (f2len (f2!@*. (f2!@+ a b) 0.1)))
    ; f2!@*. scales the vector by 0.1 by broadcasting [.] the value over the veq

    ; convenience function to print arrays of vectors:
    (2$print line) ; returns line

    (vp (f2!@$+ vb 3f0 100f0))

    ; only return vb from index to below 5
    (vp (f2!@$+ (?@ va 2 5) 3f0 100f0))

    (vp (f2dot (f2$ va) (f2$ line 1)))   ; dot product
    ; can also be written as:
    (f!@+ (f2!@* (f2$ va) (f2$ line 1))
    ; where (f2$ va) is the first veq in va, and (f2$ line 1) is the second
    ; veq in line

    (vp (f2cross (f2$ line 0 1))) ; cross product
    ; equivalent to:
    (vp (f2cross (f2$ line 0) (f2$ line 1)))

    (vp (f2!@$+ (f2$zero 3) 3f0 1f0))

    (vp (f21_@$f2len (f2!@$+ (f2$zero 3) 3f0 1f0)))

    (vp (f21_@$+ vb))

   ; TODO, improve example for new features
    ))

For more examples go to examples.

You can also see some usagee in the tests.

cl-veq's Issues

illegal OF-TYPE in COLLECT inside LOOP

cl-veq/src/lets.lisp

Line 80 in 1cf5088

collect expr of-type ',',type)))))))

the of-type in the line above is invalid, because collect does not take a type spec according to the stanrd of loop. Maybe some implementation don't error on taht, but LispWorks at least does.

It needs to simply be removed.

Can't quickload

When trying to quickload I get the following error

; file: /tmp/cl-veq/src/checks.lisp
; in: fvdef* f2in-concave
;     (VEQ:FVDEF* VEQ:F2IN-CONCAVE
;       (VEQ::SHAPE (VEQ:VARG 2 VEQ::PT))
;       (DECLARE (VEQ:FVEC VEQ::SHAPE)
;                (VEQ:FF
;                  VEQ::PT))
;       (LET ((VEQ::N (VEQ:2$NUM VEQ::SHAPE)))
;         (VEQ:MVB (VEQ::MINX VEQ::MAXX VEQ::MINY VEQ::MAXY)
;                  (VEQ:F2$MIMA VEQ::SHAPE :N VEQ::N)
;                  (DECLARE
;                   (VEQ:FF
;                     VEQ::MINX
;                     VEQ::MAXX
;                     VEQ::MINY
;                     VEQ::MAXY))
;                  (UNLESS
;                      (VEQ:F2IN-BBOX VEQ::MINX VEQ::MINY VEQ::MAXX VEQ::MAXY
;                                     VEQ::PT)
;                    (RETURN-FROM VEQ::%F2IN-CONCAVE NIL))
;                  (LET* (# # #)
;                    (DECLARE #
;                             #)
;                    (VEQ:F2$WITH-ROWS # #)
;                    (ODDP VEQ::C)))))
; --> MACROLET PROGN DEFUN PROGN SB-IMPL::%DEFUN SB-IMPL::%DEFUN 
; --> SB-INT:NAMED-LAMBDA FUNCTION BLOCK LET VEQ:MVB MULTIPLE-VALUE-BIND 
; --> MULTIPLE-VALUE-CALL FUNCTION UNLESS IF 
; ==>
;   (RETURN-FROM VEQ::%F2IN-CONCAVE NIL)
; 
; caught error:
;   return for unknown block: %f2in-concave
; Debugger entered on #<uiop/lisp-build:compile-file-error {1001F33323}>

; in: fvdef* f3planex
;     (VEQ:FVDEF* VEQ:F3PLANEX
;       ((VEQ:VARG 3 VEQ::N VEQ::P VEQ::A VEQ::B))
;       (DECLARE (OPTIMIZE (SAFETY 0) (SPEED 3) DEBUG SPACE)
;                (VEQ:FF
;                  VEQ::N
;                  VEQ::P
;                  VEQ::A
;                  VEQ::B))
;       "intersection of plane (n:normal, p:point) and line (a b)"
;       (VEQ:F3LET ((VEQ::LN (VEQ:F3- VEQ::B VEQ::A)))
;        (LET ((VEQ::LDOTN #))
;          (DECLARE
;           (VEQ:FF
;             VEQ::LDOTN))
;          (WHEN (< # VEQ:*EPS*) (RETURN-FROM VEQ::%F3PLANEX #))
;          (LET (#)
;            (DECLARE #)
;            (VEQ:~ T VEQ:D #)))))
; --> MACROLET PROGN DEFUN PROGN SB-IMPL::%DEFUN SB-IMPL::%DEFUN 
; --> SB-INT:NAMED-LAMBDA FUNCTION BLOCK VEQ:F3LET PROGN VEQ:MVB 
; --> MULTIPLE-VALUE-BIND MULTIPLE-VALUE-CALL FUNCTION LET WHEN IF 
; ==>
;   (RETURN-FROM VEQ::%F3PLANEX (VALUES NIL 0.0 0.0 0.0 0.0))
; 
; caught error:
;   return for unknown block: %f3planex

This is happening when installing from master

Refernce to sb-ext make "veq/tests" it fail to compile on other platforms

cl-veq/test/run.lisp

Line 21 in 61c4a80

(sb-ext:quit :unix-status 7)))))

I suggest you replace it by uiop:quit:

 (uiop:quit 7)

BTW: the current code relies on being in the right directory when running the tests. It is better to make the paths relative to the system, using asdf:system-relatve-pathname, for example:

(defparameter *files* 
  (mapcar #'(lambda(relative-path)
              (asdf:system-relative-pathname "veq/tests" relative-path))
          `(#P"test/veq.lisp" #P"test/macro.lisp" #P"test/arr-with.lisp"
                              #P"test/arr.lisp" #P"test/checks.lisp" #P"test/mat.lisp")))

Tests failed: error in arr tests.

During preparation your project for Guix downstream I've faced with failing test on ECS implementation.

starting phase `check'
Invoking ecl: "/gnu/store/gbahff6l8b6413vx52klkljr7ypmpz6c-ecl-23.9.9/bin/ecl" "--eval" "(require :asdf)" "--eval" "(asdf:initialize-source-registry (list :source-registry (list :tree (uiop:ensure-pathname \"/gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq\" :truenamize t :ensure-directory t)) :inherit-configuration))" "--eval" "(asdf:test-system \"veq\")" "--eval" "(quit)"
;;; Loading #P"/gnu/store/gbahff6l8b6413vx52klkljr7ypmpz6c-ecl-23.9.9/lib/ecl-23.9.9/asdf.fas"
;;; Warning: System definition file #P"/gnu/store/q4wna8929fs4p6wv8qw1j6s7450kmjpf-ecl-cl-colors-0.0.0-1.8274105/share/common-lisp/ecl/cl-colors/cl-colors.asd" contains definition for system "cl-colors-tests". Please only define "cl-colors" and secondary systems with a name starting with "cl-colors/" (e.g. "cl-colors/test") in that file.
;;;
;;; Compiling /gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq/test/run.lisp.
;;; OPTIMIZE levels: Safety=2, Space=0, Speed=3, Debug=0
;;;
;;; Finished compiling /gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq/test/run.lisp.
;;;

starting tests in: /gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq/test/veq.lisp
.......
 Did 7 checks.
    Pass: 7 (100%)
    Fail: 0 (  0%)
done: /gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq/test/veq.lisp

starting tests in: /gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq/test/macro.lisp
..
 Did 2 checks.
    Pass: 2 (100%)
    Fail: 0 (  0%)
done: /gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq/test/macro.lisp

starting tests in: /gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq/test/macro-vv.lisp
....
 Did 4 checks.
    Pass: 4 (100%)
    Fail: 0 (  0%)
done: /gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq/test/macro-vv.lisp

starting tests in: /gnu/store/75swz2w62w0arb19cf6qq8f20cggmhxv-ecl-veq-3.0.0-1.6f8041a/share/common-lisp/ecl/veq/test/arr.lisp
...f.
 Did 5 checks.
    Pass: 4 ( 80%)
    Fail: 1 ( 20%)

 Failure Details:
 --------------------------------
 shapes:
   Did 4 checks. (planned UNSPECIFIED tests)
    Pass: 3 ( 75%)
    Fail: 1 ( 25%)

   Failure Details:
   --------------------------------
   (no description):
      #(4.0 0.0 3.541824 1.8588928 2.2722588 3.2919354 0.48214626 3.9708354
        -1.4184198 3.7400649 -2.994043 2.6524906 -3.8837676 0.9572618 -3.8837671
        -0.9572634 -2.9940426 -2.652491 -1.4184183 -3.7400653 0.48214698
        -3.9708354 2.2722597 -3.291935 3.541825 -1.8588911)
          is expected to be
      #(4.0 0.0 3.541824 1.8588928 2.2722588 3.2919354 0.48214626 3.9708354
        -1.4184198 3.7400649 -2.994043 2.6524906 -3.8837676 0.9572618 -3.8837671
        -0.95726335 -2.9940426 -2.652491 -1.4184183 -3.7400653 0.48214698
        -3.9708354 2.27226 -3.291935 3.541825 -1.8588911)
 --------------------------------
 --------------------------------
An error occurred during initialization:
error in arr tests.

Function names

First of all: I like your projects, they are very interesting!

I would be really happy if you could describe what the functions do somewhere and what their names mean. For example "f2$+". I just can't find anywhere a notation definition.