viva_tensor

-module(viva_tensor@hdc).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/viva_tensor/hdc.gleam").
-export([new/1, random/2, bind/2, similarity/2, permute/2, dim/1]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " HDC - Hyperdimensional Computing\n"
    "\n"
    " \"One-shot learning via binary vectors\"\n"
    "\n"
    " Operations on high-dimensional binary vectors (default 10,048 dimensions).\n"
    "\n"
    " ## Core Concepts\n"
    "\n"
    " - **Binding**: XOR operation. Associates two concepts. Invertible (A XOR B XOR B = A).\n"
    " - **Bundling**: Majority vote. Combines multiple vectors into a superposition.\n"
    " - **Permutation**: Cyclic shift. Encodes sequence/order.\n"
    " - **Similarity**: Hamming distance. Measures relatedness (1.0 = identical, 0.5 = random).\n"
    "\n"
    " ## Example\n"
    "\n"
    " ```gleam\n"
    " import viva_tensor/hdc\n"
    "\n"
    " let a = hdc.random(seed: 1)\n"
    " let b = hdc.random(seed: 2)\n"
    " let c = hdc.bind(a, b)\n"
    "\n"
    " hdc.similarity(c, a) // -> 0.5 (orthogonal)\n"
    " hdc.similarity(hdc.bind(c, b), a) // -> 1.0 (retrieved)\n"
    " ```\n"
).

-file("src/viva_tensor/hdc.gleam", 37).
?DOC(" Create a new empty hypervector (all zeros)\n").
-spec new(integer()) -> viva_tensor@core@ffi:hdc_vector_ref().
new(Dim) ->
    Vec@1 = case viva_tensor@core@ffi:hdc_create(Dim) of
        {ok, Vec} -> Vec;
        _assert_fail ->
            erlang:error(#{gleam_error => let_assert,
                        message => <<"Pattern match failed, no pattern matched the value."/utf8>>,
                        file => <<?FILEPATH/utf8>>,
                        module => <<"viva_tensor/hdc"/utf8>>,
                        function => <<"new"/utf8>>,
                        line => 38,
                        value => _assert_fail,
                        start => 1110,
                        'end' => 1150,
                        pattern_start => 1121,
                        pattern_end => 1128})
    end,
    Vec@1.

-file("src/viva_tensor/hdc.gleam", 43).
?DOC(" Create a random hypervector\n").
-spec random(integer(), integer()) -> viva_tensor@core@ffi:hdc_vector_ref().
random(Dim, Seed) ->
    Vec@1 = case viva_tensor@core@ffi:hdc_random(Dim, Seed) of
        {ok, Vec} -> Vec;
        _assert_fail ->
            erlang:error(#{gleam_error => let_assert,
                        message => <<"Pattern match failed, no pattern matched the value."/utf8>>,
                        file => <<?FILEPATH/utf8>>,
                        module => <<"viva_tensor/hdc"/utf8>>,
                        function => <<"random"/utf8>>,
                        line => 44,
                        value => _assert_fail,
                        start => 1246,
                        'end' => 1292,
                        pattern_start => 1257,
                        pattern_end => 1264})
    end,
    Vec@1.

-file("src/viva_tensor/hdc.gleam", 52).
?DOC(
    " Bind two hypervectors (XOR)\n"
    "\n"
    " Use to associate concepts: bind(role, filler)\n"
    " e.g., bind(key_name, \"Alice\")\n"
).
-spec bind(
    viva_tensor@core@ffi:hdc_vector_ref(),
    viva_tensor@core@ffi:hdc_vector_ref()
) -> viva_tensor@core@ffi:hdc_vector_ref().
bind(A, B) ->
    Res@1 = case viva_tensor@core@ffi:hdc_bind(A, B) of
        {ok, Res} -> Res;
        _assert_fail ->
            erlang:error(#{gleam_error => let_assert,
                        message => <<"Pattern match failed, no pattern matched the value."/utf8>>,
                        file => <<?FILEPATH/utf8>>,
                        module => <<"viva_tensor/hdc"/utf8>>,
                        function => <<"bind"/utf8>>,
                        line => 53,
                        value => _assert_fail,
                        start => 1485,
                        'end' => 1524,
                        pattern_start => 1496,
                        pattern_end => 1503})
    end,
    Res@1.

-file("src/viva_tensor/hdc.gleam", 63).
?DOC(
    " Calculate similarity between two vectors\n"
    "\n"
    " Returns Float in [0.0, 1.0]\n"
    " 1.0 = Identical\n"
    " 0.5 = Orthogonal (Unrelated)\n"
    " 0.0 = Opposite (but in HDC usually everything is >= 0.5)\n"
).
-spec similarity(
    viva_tensor@core@ffi:hdc_vector_ref(),
    viva_tensor@core@ffi:hdc_vector_ref()
) -> float().
similarity(A, B) ->
    Sim@1 = case viva_tensor@core@ffi:hdc_similarity(A, B) of
        {ok, Sim} -> Sim;
        _assert_fail ->
            erlang:error(#{gleam_error => let_assert,
                        message => <<"Pattern match failed, no pattern matched the value."/utf8>>,
                        file => <<?FILEPATH/utf8>>,
                        module => <<"viva_tensor/hdc"/utf8>>,
                        function => <<"similarity"/utf8>>,
                        line => 64,
                        value => _assert_fail,
                        start => 1792,
                        'end' => 1837,
                        pattern_start => 1803,
                        pattern_end => 1810})
    end,
    Sim@1.

-file("src/viva_tensor/hdc.gleam", 72).
?DOC(
    " Permute vector (cyclic shift)\n"
    "\n"
    " Use to encode sequence or order.\n"
    " permute(A, 1) is different from A, but related.\n"
).
-spec permute(viva_tensor@core@ffi:hdc_vector_ref(), integer()) -> viva_tensor@core@ffi:hdc_vector_ref().
permute(Vec, Shift) ->
    Res@1 = case viva_tensor@core@ffi:hdc_permute(Vec, Shift) of
        {ok, Res} -> Res;
        _assert_fail ->
            erlang:error(#{gleam_error => let_assert,
                        message => <<"Pattern match failed, no pattern matched the value."/utf8>>,
                        file => <<?FILEPATH/utf8>>,
                        module => <<"viva_tensor/hdc"/utf8>>,
                        function => <<"permute"/utf8>>,
                        line => 73,
                        value => _assert_fail,
                        start => 2038,
                        'end' => 2086,
                        pattern_start => 2049,
                        pattern_end => 2056})
    end,
    Res@1.

-file("src/viva_tensor/hdc.gleam", 78).
?DOC(" Get dimensionality of the vector\n").
-spec dim(viva_tensor@core@ffi:hdc_vector_ref()) -> integer().
dim(Vec) ->
    D@1 = case viva_tensor@core@ffi:hdc_dim(Vec) of
        {ok, D} -> D;
        _assert_fail ->
            erlang:error(#{gleam_error => let_assert,
                        message => <<"Pattern match failed, no pattern matched the value."/utf8>>,
                        file => <<?FILEPATH/utf8>>,
                        module => <<"viva_tensor/hdc"/utf8>>,
                        function => <<"dim"/utf8>>,
                        line => 79,
                        value => _assert_fail,
                        start => 2173,
                        'end' => 2208,
                        pattern_start => 2184,
                        pattern_end => 2189})
    end,
    D@1.