fluidcell

Quantities like the root densities of TBAs are functions of position and rapidity. Additionally, some TBAs contain multiple root densitites, each describing a different type of quasiparticle. Thus, the numerical representation of the root density can be achieved with a rank-3 tensor.

Meanwhile, quantites like the two-body scattering phase encodes the interaction between two quasiparticles of (potentially) different type and rapidity. Thus, an extra type and rapidity arguement are needed resulting in a rank-5 tensor representation.

Consider one of the most central operations of GHD calculations, namely the dressing of some quantity, h. This implies solving the set of linear equations:

We won't be going into specifics regarding the quantities of the equation, however, the subscripts mark the rapidity indices, while the superscripts mark the quasiparticle type indices. The calculation requires contracting over two indices - similar to a matrix multiplication, which is just the contraction over a single index,

The fluidcell class wraps around a standard Matlab 5-dimensional matrix and generalizes many of the standard 2-dimensional methods (such as matrix multiplication) to 4D. Thus, the multiplication above can be computed in iFluid via h = U*h_dr or solving the equation via h_dr = U\h.

To achieve this, the fluidcell class enforces a strict convention for indices, namely

  1. Main rapidity index.
  2. Position index.
  3. Main type index.
  4. Secondary rapidity index.
  5. Secondary type index.

The purpose of the fluidcell is to perform multi-index contractions using the standard Matlab notation, which is achieved by overloading the mathematical operators + - ./ * .* \ .^.

The indices of the fluidcell can be accessed using the standard Matlab referencing for arrays. Similarly, the index labels (name of indices) can be used for referencing as well.

A = B(:,:,3)        % returns the 3rd type index of B
B(:,:,3) = A        % sets the 3rd type index of B equal to A
A = B('type',3)     % returns the 3rd type index of B
B('type',3) = A     % sets the 3rd type index of B equal to A

Constructor

An fluidcell object can be initialized using a MAtlab ND-array, which the fluidcell will then wrap around.

obj = fluidcell(A)

Construct an fluidcell object using the ND-array input A as datastructure.
Inputs:

  • A: Standard Matlab ND-array up to 5 dimensions.

Returns:

  • obj: fluidcell object.

obj = fluidcell.zeros(d1, d2, ... , dN )

or

obj = fluidcell.zeros( [d1, d2, ... , dN] )

Construct an fluidcell object of zeros with indices of specified sizes (up to N = 5 indices).
Inputs:

  • d1, d2, ... , dN: Integers indicating size of the n'th index.

Returns:

  • obj: fluidcell object.

obj = fluidcell.ones(d1, d2, ... , dN )

or

obj = fluidcell.ones( [d1, d2, ... , dN] )

Construct an fluidcell object of ones with indices of specified sizes (up to N = 5 indices).
Inputs:

  • d1, d2, ... , dN: Integers indicating size of the n'th index.

Returns:

  • obj: fluidcell object.

obj = fluidcell.eye( d_rapid, d_type )

Construct a "square" fluidcell object with ones at entries with matching rapidity and type indices.
Inputs:

  • d_rapid: Integer indicating size of the main and secondary rapidity index.
  • d_type: Integer indicating size of the main and secondary type index.

Returns:

  • obj: fluidcell object.

Accessor methods

S = size(obj, idx)

Returns size of entire tensor or one of its indices.
Inputs:

  • idx: (optional) Index in question.

Returns:

  • S: Sizes of all or specified index.

out = double(obj)

Returns tensor as standard Matlab matrix of doubles.

Returns:

  • out: Underlying matrix.

Index manipulation methods

out = flatten(obj)

Returns a 3-dimensional matrix. The first index is the main rapidity index merged with the main type index. The second index is the secondary rapidity index merged with the secondary type index. The third index is the spatial index.

Returns:

  • out: Flattened tensor.

out = unflatten(obj)

Undoes the flatten() transformation.

Returns:

  • out: Un-flattened tensor.

out = transpose(obj) / out = t(obj)

Returns tensor with both the two rapidity and the two type indices permuted.

Returns:

  • out: Transposed tensor.

Mathematical operators

The fluidcell class overloads the elementwise mathematically operations + - ./ .* .^ along with

  • abs()
  • log()
  • exp()

Below are the overloaded methods, which have a different function than their Matlab counterpart.

C = mtimes(A, B) / C = A*B

Performs the two-index contraction

Inputs:

  • A: Matrix or tensor with dimensions ( Ra, Xa, Ta, N, L ), with position index length, Xa, equal to 1 or M.
  • B: Matrix or tensor with dimensions ( N, Xb, L, Rb, Tb ), with position index length, Xb, equal to 1 or M.

Returns:

  • C: Matrix or tensor with dimensions ( Ra, max(Xa, Xb), Ta, Rb, Tb ).

x = mldivide(A, B) / x = A\B

Solves the system of linear equations

Inputs:

  • A: Matrix or tensor with dimensions ( N, Xa, L, Ra, Ta ), with position index length, Xa, equal to 1 or M.
  • B: Matrix or tensor with dimensions ( N, Xb, L, Rb, Tb ), with position index length, Xb, equal to 1 or M.

Returns:

  • x: Matrix or tensor with dimensions ( Ra, max(Xa, Xb), Ta, Rb, Tb ).

B = inv(A)

Returns the solution to the equations

Inputs:

  • A: Tensor with both rapidity indices and both type indices of equal length.

Returns:

  • B: "Inverse" of A.

out = sum(obj, idx, t_str)

Returns the tensor summed over the given index.
Inputs:

  • idx: Integer, or vector of integers, indicating the index in quation.
  • t_str: (optional) String indicating output type:
    • 'd'/'double': Returns standard Matlab matrix of doubles.
    • 't'/'tensor': Returns fluidcell.

Returns:

  • out: Sum over index.