emmy.structure — org.mentat/emmy 0.32.0

*allow-incompatible-multiplication* clj/s

basis-unit clj/s

(basis-unit i)

(basis-unit n i)

Returns a basis sequence of n 0s, with 1 in the ith position.

If n is not supplied returns an infinite sequence.

compatible-shape clj/s

(compatible-shape s)

Returns a structure compatible for multiplication with s down to a scalar, with the slots filled with gensyms.

compatible-zero clj/s

(compatible-zero s)

Returns a structure compatible for multiplication with s down to 0.

component clj/s

(component & indices)

Given an access chain (a sequence of indices), return a function that accepts a structure and returns the element at the specified access chain.

dimension clj/s

(dimension s)

If s is sequential, returns its dimension, i.e., the total number of non-sequential entries in the structure. Else, returns 1.

down clj/s

(down & xs)

Construct a down (covariant) tuple from the arguments. Variadic version of down*.

down* clj/s

(down* xs)

Construct a down (covariant) tuple from the supplied sequence. For a variadic version, see down.

down-of-ups? clj/s

(down-of-ups? s)

Returns true if s is a down structure containing all up structures of the same size, false otherwise.

down? clj/s

(down? s)

Returns true if s is a down structure, false otherwise.

dual-zero clj/s

Alias for compatible-zero.

fold-chain clj/s

(fold-chain f s)

(fold-chain f init s)

(fold-chain f init present s)

Returns the result of accumulating all non-structural entries in s using the supplied fold function f into the optional accumulator init (defaults to (f)).

f must be a 2-argument fn of type (accumulator, [x chain orientations]) => accumulator responsible for merging some value x into the ongoing accumulation. The second argument is a 3-vector containing

• the entry in the structure
• a vector of its 'access chain', i.e., the path you'd pass to [[clojure.core/get-in]] to access the entry
• a vector of orientations associated with each index in the access chain

f should return a new instance of the accumulator.

Additional arities allow you to supply

• init, the initial (empty) accumulator (defaults to (f))
• present, a function that will be applied to the final, aggregated result (defaults to f)

For example:

(fold-chain
  (fn ([] [])
   ([acc] acc)
   ([acc [s chain orientations]]
    (conj acc {:s s
               :chain chain
               :orientations orientations})))
  (s/down (s/up 1 2) (s/up 3 4)))

[{:s 1, :chain [0 0], :orientations [::s/down ::s/up]}
 {:s 2, :chain [0 1], :orientations [::s/down ::s/up]}
 {:s 3, :chain [1 0], :orientations [::s/down ::s/up]}
 {:s 4, :chain [1 1], :orientations [::s/down ::s/up]}]

generate clj/s

(generate dimension orientation f)

Generate a structure with the given orientation whose elements are

(f i)

where i ranges from [0..dimension).

kronecker clj/s

(kronecker i j)

Returns 1 if i== j, 0 otherwise.

literal clj/s

(literal sym size orientation)

Generates a structure of the specified orientation and dimension size populated by symbolic entries, each prefixed by the supplied symbol sym.

For example:

(= (literal 'x 3 ::s/up) (up 'x↑0 'x↑1 'x↑2))

See literal-up and literal-down for constructors with baked in orientations.

literal-down clj/s

(literal-down sym size)

Generates a down structure of dimension size populated by symbolic entries, each prefixed by the supplied symbol sym.

For example:

(= (literal-down 'x 3)
   (down 'x_0 'x_1 'x_2))

literal-up clj/s

(literal-up sym size)

Generates an up structure of dimension size populated by symbolic entries, each prefixed by the supplied symbol sym.

For example:

(= (literal-up 'x 3)
   (up 'x↑0 'x↑1 'x↑2))

make clj/s

(make orientation xs)

Generate a structure with the supplied orientation, given some sequence xs

map-chain clj/s

(map-chain f s)

Returns a new structure of equivalent shape to s, generated by applying f to three arguments:

• the entry in the structure
• a vector of its 'access chain', i.e., the path you'd pass to [[clojure.core/get-in]] to access the entry
• a vector of orientations associated with each index in the access chain

For example:

(dorun (map-chain println (s/down (s/up 1 2) (s/up 3 4))))

1 [0 0] [::s/down ::s/up]
2 [0 1] [::s/down ::s/up]
3 [1 0] [::s/down ::s/up]
4 [1 1] [::s/down ::s/up]

mapr clj/s

(mapr f & structures)

Return a structure with the same shape as s but with f applied to each primitive (that is, not structural) component.

opposite clj/s

(opposite s)

(opposite s xs)

For a non-[[Structure]] s, the single-arity case acts as [[identity]]. For a [[Structure]], returns an identical structure with its orientation reversed (up becomes down, down becomes up).

NOTE that a vector is interpreted as an up structure, so:

(opposite [1 2 3]) ;;=> (down 1 2 3)

The two-arity case returns a new [[Structure]] of opposite orientation to s with the contents of the sequence xs.

opposite-orientation clj/s

orientation clj/s

(orientation s)

Returns the orientation of s, either ::up or ::down. Defaults to ::up, even for non-structures.

same clj/s

(same s xs)

Returns a structure containing xs with the same orientation as s.

same-orientation? clj/s

(same-orientation? s t)

Returns true if the supplied structures have the same orientation, false otherwise.

structure->access-chains clj/s

(structure->access-chains s)

Return a structure of the same shape as s whose elements are access chains corresponding to position of each element (i.e., the sequence of indices needed to address that element via [[get-in]]).

Each access chain has the sequence of orientations (::s/up, ::s/down) associated with each step attached to it as metadata, under an :orientations key. Use this if the orientation of the indices matters.

structure->prototype clj/s

(structure->prototype name s)

Accepts

• some symbolic (or string) name
• a structure s

and returns a new structure of identical shape, with symbolic entries like 'x↑0_1 that show their access chain with proper orientations for each step.

structure->vector clj/s

(structure->vector s)

Return the structure s in unoriented vector form.

structure? clj/s

(structure? s)

Returns true if s is a structure, false otherwise. (Vectors are treated as up structures.)

sumr clj/s

(sumr f & structures)

Given some function f and any number of isomorphic structures, returns the sum of the results of applying f to each associated set of entries in each structure.

transpose clj/s

(transpose s)

Returns a structure with the same shape as s, with all orientations inverted.

transpose-outer clj/s

(transpose-outer s)

Returns a new structure with the same orientation as the first element of s, filled with elements of the same orientation as s.

Each element is generating by taking the first element of each entry in s, the the second, etc... In that sense this is similar to a traditional matrix transpose.

A comment from scmutils states:

'used only in symmetrize-Christoffel in src/calculus/covariant-derivative.scm.'

two-down? clj/s

(two-down? s)

Returns true if s is a down structure containing all down structures of the same size, false otherwise.

two-tensor-info clj/s

(two-tensor-info s)

Given an up or down structure containing structures of the same orientation and size (a 2 tensor), returns a dictionary with keys:

{:outer-orientation <::up or ::down>
 :inner-orientation <::up or ::down>
 :outer-size <int>
 :inner-size <int>}

If `s` is _not_ a valid tensor, returns nil.

two-tensor? clj/s

(two-tensor? s)

Returns true if s is an up or down structure containing all up or down structures of internally-matching orientation and size, false otherwise.

two-up? clj/s

(two-up? s)

Returns true if s is an up structure containing all up structures of the same size, false otherwise.

typical-object clj/s

(typical-object s)

Returns a structure of the same shape and orientation as s, generated by substituting gensymmed symbols in for each entry.

unflatten clj/s

(unflatten values struct)

(unflatten constructor values struct)

Given:

• a sequence of values
• a model struct

Returns a new structure generated by unpacking values into a structure with the same shape as struct.

up clj/s

(up & xs)

Construct an up (contravariant) tuple from the arguments.

Variadic version of up*.

up* clj/s

(up* xs)

Construct an up (contravariant) tuple from the supplied sequence. For a variadic version, see up.

up-of-downs? clj/s

(up-of-downs? s)

Returns true if s is an up structure containing all down structures of the same size, false otherwise.

up? clj/s

(up? s)

Returns true if s is an up structure, false otherwise.

valid-orientation? clj/s

(valid-orientation? o)

Returns true if the supplied orientation lives in the set of allowed orientations, false otherwise.

vector->down clj/s

(vector->down v)

Form a down-tuple from a vector.

NOTE that this is an alias of down* that is more restrictive, in that it only accepts a vector. Use down* if you'd like to pass an arbitrary sequence. (If you pass a vector to down*) it will be just as efficient.

vector->up clj/s

(vector->up v)

Form an up-tuple from a vector.

NOTE that this is an alias of up* that is more restrictive, in that it only accepts a vector. Use up* if you'd like to pass an arbitrary sequence. (If you pass a vector to up*) it will be just as efficient.

vector-dot-product clj/s

(vector-dot-product v1 v2)

Returns the (vector) dot product of v1 and v2; this is equivalent to the sum of the pairwise product of each entry.

The arguments must have identical length, and all pairwise entries must be compatible via [[g/*]].

vector-inner-product clj/s

(vector-inner-product v1 v2)

Returns the (vector) inner product of v1 and v2; this is equivalent to the sum of the pairwise product of each entry.

This is equivalent to vector-dot-product with every element of v1 transformed into its complex conjugate.

The arguments must have identical length, and all pairwise entries must be compatible via [[g/*]].