field_einsum

hcipy.field.field_einsum(subscripts, *operands, **kwargs)

Evaluates the Einstein summation convention on the operand fields.

This function uses the same conventions as numpy.einsum(). The input subscript is multiplexed over each position in the grid. The grids of each of the input field operands don’t have to match, but must have the same lengths.

The subscripts must be written as you would for a single position in the grid. The function alters these subscripts to multiplex over the entire grid.

Caution

Some subscripts may yield no exception, even though they would fail for a single point in the grid. The output in these cases can not be trusted.

Parameters:
subscriptsstr

Specifies the subscripts for summation.

operandslist of array_like or Field

These are the arrays or fields for the operation.

out{ndarray, None}, optional

If provided, the calculation is done into this array.

dtype{data-type, None}, optional

If provided, forces the calculation to use the data type specified. Note that you may have to also give a more liberal casting parameter to allow the conversions. Default is None.

order{‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the output. ‘C’ means it should be C contiguous. ‘F’ means it should be Fortran contiguous, ‘A’ means it should be ‘F’ if the inputs are all ‘F’, ‘C’ otherwise. ‘K’ means it should be as close to the layout as the inputs as is possible, including arbitrarily permuted axes. Default is ‘K’.

casting{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur. Setting this to ‘unsafe’ is not recommended, as it can adversely affect accumulations.

  • ‘no’ means the data types should not be cast at all.

  • ‘equiv’ means only byte-order changes are allowed.

  • ‘safe’ means only casts which can preserve values are allowed.

  • ‘same_kind’ means only safe casts or casts within a kind,

    like float64 to float32, are allowed.

  • ‘unsafe’ means any data conversions may be done.

Default is ‘safe’.

optimize{False, True, ‘greedy’, ‘optimal’}, optional

Controls if intermediate optimization should occur. No optimization will occur if False and True will default to the ‘greedy’ algorithm. Also accepts an explicit contraction list from the np.einsum_path function. See np.einsum_path for more details. Default is False.

Returns:
Field

The calculated Field based on the Einstein summation convention.

Raises:
ValueError

If all of the fields don’t have the same grid size. If the number of operands is not equal to the number of subscripts specified.