Add embed_lazy API

[arnavk23]

Closes #523.

Motivation

The existing embed function materialises the full tensor-product operator into a dense or sparse matrix immediately. When building Hamiltonians over large composite Hilbert spaces, this forces an unnecessary and often expensive materialisation before the operator is ever applied to a state.

embed_lazy solves this by keeping the embedded operator in lazy form, deferring all matrix construction until the caller explicitly calls dense or sparse.

Tests

• test/test_timeevolution_tdops.jl - tests embed_lazy in the context of TimeDependentSum, which has no embed method, confirming the fix for the original issue.

• test/test_steadystate.jl - confirming embed_lazy on a non-composite basis returns the operator unchanged.

# Single operator at one index
embed_lazy(basis::CompositeBasis, index::Int, op::AbstractOperator) -> LazyTensor

# Multiple operators at multiple indices (their product)
embed_lazy(basis::CompositeBasis, indices, operators) -> LazyTensor

# LazySum at one index — distributes embed_lazy over summands
embed_lazy(basis::CompositeBasis, index::Int, op::LazySum) -> LazySum

# Non-composite basis — identity (no embedding needed)
embed_lazy(basis, index, op) -> op

Comparison with embed

	embed	embed_lazy
Return type	DenseOperator / SparseOperator	LazyTensor / LazySum
Materialisation	Immediate	Deferred until dense/sparse
Works with TimeDependentSum	✗	✓
Memory cost at construction	O(N²)	O(subsystem size)

[github-actions]

Benchmark Results (Julia v1)

Time benchmarks

	master	d83c5e8...	master / d83c5e8...
master/base array types/1//2	26.1 ± 8.4 μs	25.9 ± 8.1 μs	1.01 ± 0.45
master/base array types/100//1	19 s	18.5 s	1.03
master/base array types/20//1	0.0461 ± 0.0011 s	0.0454 ± 0.00062 s	1.02 ± 0.029
master/base array types/50//1	1.28 ± 0.018 s	1.28 ± 0.016 s	1 ± 0.019
master/qo types/1//2	31.2 ± 9.4 μs	30.4 ± 9.1 μs	1.03 ± 0.44
master/qo types/100//1	15.6 s	15.5 s	1
master/qo types/20//1	0.0376 ± 0.0013 s	0.0351 ± 0.00072 s	1.07 ± 0.042
master/qo types/50//1	1.09 ± 0.013 s	1.07 ± 0.029 s	1.03 ± 0.031
schroedinger/base array types/1//2	6.7 ± 0.39 μs	6.47 ± 0.37 μs	1.04 ± 0.085
schroedinger/base array types/100//1	3.35 ± 0.068 ms	3.36 ± 0.065 ms	0.996 ± 0.028
schroedinger/base array types/20//1	0.136 ± 0.0068 ms	0.135 ± 0.0068 ms	1.01 ± 0.071
schroedinger/base array types/50//1	0.708 ± 0.019 ms	0.71 ± 0.019 ms	0.997 ± 0.038
schroedinger/qo types/1//2	7.07 ± 0.43 μs	6.83 ± 0.43 μs	1.04 ± 0.091
schroedinger/qo types/100//1	3.22 ± 0.047 ms	3.21 ± 0.045 ms	1 ± 0.02
schroedinger/qo types/20//1	0.224 ± 0.011 ms	0.223 ± 0.011 ms	1 ± 0.07
schroedinger/qo types/50//1	0.772 ± 0.016 ms	0.771 ± 0.017 ms	1 ± 0.03
stochastic master/base array types/1//2	0.239 ± 0.062 ms	0.234 ± 0.067 ms	1.02 ± 0.39
stochastic master/base array types/100//1	0.246 ± 0.018 s	0.249 ± 0.022 s	0.987 ± 0.11
stochastic master/base array types/20//1	28.1 ± 0.44 ms	28.2 ± 0.44 ms	0.996 ± 0.022
stochastic master/base array types/50//1	0.0776 ± 0.0051 s	0.0779 ± 0.0046 s	0.996 ± 0.088
stochastic master/qo types/1//2	0.276 ± 0.057 ms	0.269 ± 0.054 ms	1.03 ± 0.3
stochastic master/qo types/100//1	0.6 ± 0.012 s	0.584 ± 0.018 s	1.03 ± 0.038
stochastic master/qo types/20//1	23.9 ± 0.55 ms	23.7 ± 0.38 ms	1.01 ± 0.029
stochastic master/qo types/50//1	0.15 ± 0.0068 s	0.146 ± 0.0049 s	1.03 ± 0.058
stochastic schroedinger/base array types/1//2	0.0589 ± 0.0017 ms	0.0588 ± 0.0018 ms	1 ± 0.041
stochastic schroedinger/base array types/100//1	1.03 ± 0.036 ms	1.04 ± 0.045 ms	0.995 ± 0.056
stochastic schroedinger/base array types/20//1	0.281 ± 0.013 ms	0.276 ± 0.013 ms	1.02 ± 0.066
stochastic schroedinger/base array types/50//1	0.628 ± 0.018 ms	0.629 ± 0.018 ms	0.999 ± 0.04
stochastic schroedinger/qo types/1//2	0.0703 ± 0.01 ms	0.0699 ± 0.0093 ms	1.01 ± 0.2
stochastic schroedinger/qo types/100//1	1.48 ± 0.027 ms	1.46 ± 0.026 ms	1.01 ± 0.026
stochastic schroedinger/qo types/20//1	0.334 ± 0.015 ms	0.345 ± 0.017 ms	0.97 ± 0.064
stochastic schroedinger/qo types/50//1	0.775 ± 0.02 ms	0.761 ± 0.018 ms	1.02 ± 0.035
time_to_load	2.6 ± 0.016 s	2.59 ± 0.042 s	1.01 ± 0.018

Memory benchmarks

	master	d83c5e8...	master / d83c5e8...
master/base array types/1//2	0.488 k allocs: 28 kB	0.488 k allocs: 28 kB	1
master/base array types/100//1	0.135 M allocs: 11.6 GB	0.135 M allocs: 11.6 GB	1
master/base array types/20//1	8.01 k allocs: 29.8 MB	8.01 k allocs: 29.8 MB	1
master/base array types/50//1	0.0376 M allocs: 0.818 GB	0.0376 M allocs: 0.818 GB	1
master/qo types/1//2	0.609 k allocs: 30.6 kB	0.609 k allocs: 30.6 kB	1
master/qo types/100//1	0.155 M allocs: 11.7 GB	0.155 M allocs: 11.7 GB	1
master/qo types/20//1	9.19 k allocs: 29.9 MB	9.19 k allocs: 29.9 MB	1
master/qo types/50//1	0.0429 M allocs: 0.817 GB	0.0429 M allocs: 0.817 GB	1
schroedinger/base array types/1//2	0.073 k allocs: 4.5 kB	0.073 k allocs: 4.5 kB	1
schroedinger/base array types/100//1	0.089 k allocs: 0.0538 MB	0.089 k allocs: 0.0538 MB	1
schroedinger/base array types/20//1	0.073 k allocs: 15 kB	0.073 k allocs: 15 kB	1
schroedinger/base array types/50//1	0.073 k allocs: 31.8 kB	0.073 k allocs: 31.8 kB	1
schroedinger/qo types/1//2	0.084 k allocs: 5 kB	0.084 k allocs: 5 kB	1
schroedinger/qo types/100//1	0.098 k allocs: 0.0481 MB	0.098 k allocs: 0.0481 MB	1
schroedinger/qo types/20//1	0.084 k allocs: 14.2 kB	0.084 k allocs: 14.2 kB	1
schroedinger/qo types/50//1	0.084 k allocs: 28.8 kB	0.084 k allocs: 28.8 kB	1
stochastic master/base array types/1//2	3.88 k allocs: 0.209 MB	3.88 k allocs: 0.209 MB	1
stochastic master/base array types/100//1	1.87 k allocs: 0.147 GB	1.87 k allocs: 0.147 GB	1
stochastic master/base array types/20//1	4.53 k allocs: 16.8 MB	4.53 k allocs: 16.8 MB	1
stochastic master/base array types/50//1	2.27 k allocs: 0.0457 GB	2.27 k allocs: 0.0457 GB	1
stochastic master/qo types/1//2	4.84 k allocs: 0.23 MB	4.84 k allocs: 0.23 MB	1
stochastic master/qo types/100//1	5.49 k allocs: 0.389 GB	5.49 k allocs: 0.389 GB	1
stochastic master/qo types/20//1	5.49 k allocs: 16.8 MB	5.49 k allocs: 16.8 MB	1
stochastic master/qo types/50//1	5.49 k allocs: 0.0984 GB	5.49 k allocs: 0.0984 GB	1
stochastic schroedinger/base array types/1//2	0.101 k allocs: 6.55 kB	0.101 k allocs: 6.55 kB	1
stochastic schroedinger/base array types/100//1	0.278 k allocs: 0.0651 MB	0.278 k allocs: 0.0651 MB	1
stochastic schroedinger/base array types/20//1	0.101 k allocs: 17 kB	0.101 k allocs: 17 kB	1
stochastic schroedinger/base array types/50//1	0.101 k allocs: 0.033 MB	0.101 k allocs: 0.033 MB	1
stochastic schroedinger/qo types/1//2	0.432 k allocs: 22.1 kB	0.432 k allocs: 22.1 kB	1
stochastic schroedinger/qo types/100//1	0.448 k allocs: 0.071 MB	0.448 k allocs: 0.071 MB	1
stochastic schroedinger/qo types/20//1	0.432 k allocs: 0.0318 MB	0.432 k allocs: 0.0318 MB	1
stochastic schroedinger/qo types/50//1	0.432 k allocs: 0.0482 MB	0.432 k allocs: 0.0482 MB	1
time_to_load	0.145 k allocs: 11 kB	0.145 k allocs: 11 kB	1

[arnavk23]

@Krastanov was going through the unitaryHACK event and also worked on this. Do check it out whenever you are free.