Help with vectors/compile and optional parameters

[nonphoto]

I have a function like this:

export function deltaFrom(start?: number, end?: number, delta?: number) {
  return delta ?? (start ?? 0) - (end ?? 1);
}

How would it be possible to use defHofOp from @thi.ng/vectors to make a generic vector version of this while still allowing optional parameters? I'm not sure how to generate a function with this signature:

function deltaFrom(out: Vec | null, start?: Vec, end?: Vec, delta?: Vec): Vec

[nonphoto]

Similarly, how would I make generic and optimized vector operations for this type with defHofOp?

interface Line {
  a: Vec;
  b: Vec;
}

function pointOnLine(s: Line, u: number) {...}

[postspectacular]

Hi @nonphoto - apologies that the code generation parts of that package are not really documented, so far they were really mainly intended for internal use only and therefore also don't have the nicest API. You could use this like so:

import type { MultiVecOp, ReadonlyVec, Vec } from "./api";
import { defHofOp } from "./compile/emit";

function $deltaFrom(start?: number, end?: number, delta?: number) {
    return delta ?? (start ?? 0) - (end ?? 1);
}

type DeltaFrom = (
    out?: Vec,
    start?: ReadonlyVec,
    end?: ReadonlyVec,
    delta?: number
) => Vec;

export const [deltaFrom, deltaFrom2, deltaFrom3, deltaFrom4] = defHofOp<
    MultiVecOp<DeltaFrom>,
    DeltaFrom
>(
    // your actual function to apply componentwise
    $deltaFrom,
    // template function for computing a single vector component
    ([o, a, b]) => `${o}=op(${a},${b},n);`,
    // function args (here with defaults)
    "o,a=[],b=[],n",
    // function args (names only)
    "o,a,b,n"
);

This results then in:

// 2D version
deltaFrom.impl(2).toString()
// '(o,a=[],b=[],n)=>{!o && (o=a);o[0]=op(a[0],b[0],n);o[1]=op(a[1],b[1],n);return o;}'

// 3D version
deltaFrom.impl(3).toString()
// '(o,a=[],b=[],n)=>{!o && (o=a);o[0]=op(a[0],b[0],n);o[1]=op(a[1],b[1],n);o[2]=op(a[2],b[2],n);return o;}'

// generic
deltaFrom.impl(0).toString()
// '(o,a=[],b=[],n)=>{!o && (o=a);for(let i=a.length;--i>=0;) {o[i]=op(a[i],b[i],n);}return o;}'

Btw. I just updated the internal code gen to correctly handle cases where the a arg is also optional (as in your case). So far I haven't encountered that case yet, so you'll have to use the latest version of thi.ng/vectors (v7.12.1, just released) to make this work properly...

---

To your second question: This function is supposed to compute the point at parametric position u, correct? There already is a polymorphic (and vector size optimized) function for this (i.e. mixN()), and to use this with your Line type, just wrap it like so:

import { mixN } from "@thi.ng/vectors";

const pointOnLine = ({a, b}: Line, u: number) => mixN([], a, b, u);

Hope that helps!

[nonphoto]

Thanks! This makes a lot of sense. My only concern is that it would be nice to be able to do this without creating any new arrays in the function args param: "o,a=[],b=[],n".

For the second question: my example was more about working with structs with vectors in them (I didn't consider that there might be a mix util already). For the purposes of the example, imagine I have some really complicated function that works with scalars instead:

interface Spring {
  start: number;
  end: number;
  damping: number;
  stiffness: number;
}

positionAt(s: Spring, t: number) {
  ... // Very long!
}

I want to make a vectorized version of this Spring type:

interface VectorSpring {
  start: Vec;
  end: Vec;
  damping: number;
  stiffness: number
}

function positionAt(s: VectorSpring, t: number) {...}

function positionAt2(s: VectorSpring, t: number) {...}

function positionAt3(s: VectorSpring, t: number) {...}

function positionAt4(s: VectorSpring, t: number) {...}

It wouldn't make sense to implement these using the existing vector ops.

Now that I'm seeing what actually gets generated from defHofOp I could probably just hard-code it as a workaround.

[postspectacular]

The empty arrays as default values are only created if the respective args are not given and I only did that because the way you wrote your scalar deltaFrom() function (all args optional). If you don't need the defaults in the vector version, just get rid of them... 😉

For your struct-based use case, I agree that defHofOp() likely isn't the right tool to use here. If you want specific 2D/3D APIs for your hypothetical physics engine, you could use a similar approach as I used for the thi.ng/boids package:

import { VEC2, VEC3, type VecAPI, type Vec, type ReadonlyVec } from "@thi.ng/vectors";

const GRAVITY2 = [0, 9.8]; // -Y up axis
const GRAVITY3 = [0, -9.8, 0]; // +Y up axis

class Particle {
  force: Vec;

  // all VecAPI impls provide size-optimized vec ops
  constructor(public vec: VecAPI, public pos: Vec, public gravity: Vec) {
    this.force = vec.zeroes();
  }

  addForce(f: ReadonlyVec, dt: number) {
    this.vec.maddN(this.force, f, dt, this.force);
  }

  updatePos() {
    // destructure if you're using multiple vec ops...
    const { add, setN } = this.vec;
    add(null, this.pos, this.force);
    setN(this.force, 0);
  }
}

// factory function for 2D particles
const particle2 = (pos: Vec, gravity: Vec = GRAVITY2) => new Particle(VEC2, pos, gravity);

// factory function for 3D particles
const particle3 = (pos: Vec, gravity: Vec = GRAVITY3) => new Particle(VEC3, pos, gravity);

[nonphoto]

Okay, I think I'll just convert my existing struct type to an array instead, so I can spread it into the function params. Thanks!

[postspectacular]

Forgot to add few more related things:

The vectors package also provides vector wrappers and versions of many vector operations for strided, memory mapped vectors and also batch operation helpers for those. Memory mapped vectors can be created via Vec2/3/4.mapBuffer() and then be used like "normal" vectors, but updating components will directly impact the underlying memory. Alternatively, the memory mapped operations use an S-suffix (for "strided") in their naming. Both approaches support AOS or SOA memory layouts... Both approaches are intended to operate directly on larger (typed) array buffers (e.g. WebGL attribute buffers, thi.ng/vector-pools buffers, thi.ng/ecs components, the upcoming mesh package etc.) and you might find them useful for your physics setup too.

import { add2, addS2, mapVectors, mulNS3, Vec2, Vec3 } from "@thi.ng/vectors";

// flat buffer encoding 3 structs of { pos: vec2, vel: vec2, color: vec3 }
// (we use padding to use a more CPU friendly element stride of 8)
// prettier-ignore
const BUF = new Float32Array([
  // pos     vel         color       padding
  1, 2,      0.1, -0.2,  1, 0.5, 0,  0,
  10, 20,    -0.1, 0.2,  0.5, 1, 0,  0,
  100, 200,  1.1, 2.2,   0, 0.5, 1,  0,
]);

const NUM = 3;
const STRIDE = 2 + 2 + 3 + 1;

// create vector views of memory
// see: https://docs.thi.ng/umbrella/vectors/classes/Vec2.html#mapBuffer
const positions = Vec2.mapBuffer(BUF, NUM, 0, 1, STRIDE);
const velocities = Vec2.mapBuffer(BUF, NUM, 2, 1, STRIDE);
// same thing for vec3
const colors = Vec3.mapBuffer(BUF, NUM, 4, 1, STRIDE);

const show = () => {
    for (let i = 0; i < NUM; i++) {
        console.log(
            positions[i].toString(),
            velocities[i].toString(),
            colors[i].toString()
        );
    }
};

show();
// [1.000, 2.000] [0.100, -0.200] [1.000, 0.500, 0.000]
// [10.000, 20.000] [-0.100, 0.200] [0.500, 1.000, 0.000]
// [100.000, 200.000] [1.100, 2.200] [0.000, 0.500, 1.000]

// add velocities to each position, update in-place
mapVectors(add2, positions, positions, velocities);

// show updated positions
for (let p of positions) console.log(p.toString());
// [1.100, 1.800]
// [9.900, 20.200]
// [101.100, 202.200]

// updated memory
console.log(BUF);
// Float32Array(24) [ 1.100000023841858, 1.7999999523162842, 0.10000000149011612, -0.20000000298023224, 1, 0.5, 0, 0, 9.899999618530273, 20.200000762939453, -0.10000000149011612, 0.20000000298023224, 0.5, 1, 0, 0, 101.0999984741211, 202.1999969482422, 1.100000023841858, 2.200000047683716, 0, 0.5, 1, 0 ]

// now an alternative approach _without_ wrapped vector types
// directly operating on the underlying buffer...

// add velocities to positions
for (let i = 0, offset = 0; i < NUM; i++, offset += STRIDE) {
    addS2(
        // output buffer
        BUF,
        // position buffer
        BUF,
        // velocity buffer
        BUF,
        // output start index
        offset,
        // position start index
        offset,
        // velocity start index
        offset + 2
    );
    // fade each item's color to 80% (using same approach)
    mulNS3(BUF, BUF, 0.8, offset + 4, offset + 4);
}

show();
// [1.200, 1.600] [0.100, -0.200] [0.800, 0.400, 0.000]
// [9.800, 20.400] [-0.100, 0.200] [0.400, 0.800, 0.000]
// [102.200, 204.400] [1.100, 2.200] [0.000, 0.400, 0.800]

If you're interested in this approach I also encourage you to check out these somewhat related packages (and their examples):

• https://thi.ng/vector-pools
• https://thi.ng/soa
• https://thi.ng/simd
• https://thi.ng/malloc