,VhdZddlmZddlmZddlmZmZmZm Z m Z m Z m Z m Z mZmZmZddlmZmZmZmZmZmZddlmZmZmZmZmZmZmZm Z gdZ!ede"ee d fZ#Gd d Z$d e#d e e"de e"fdZ%e dZ&dee&efdee&effdZ'edddddde(dede)ded e#de)dedeee$ffdZ*eddddddedeeee"fde)ded e#de)dedeee$ffdZ*ddddddedede)ded e#de)dedeee$ffdZ*ejVdededefdZ,ded ee"d!fdefd"Z-ej\dAded ee"d!fd#e(defd$Z/ej`dAded%ed ee"d!fd#e(def d&Z1ed!d!d!d!d!d'de(ded(ede)ded e#d#ededefd)Z2ed!d!d!d!d!d'dedeeee"fd(ede)ded e#d#ededefd*Z2ddddd+d'dee(efdeeee"fd(e ede)ded e#d#ededefd,Z2edd-e3de(fd.Z4dede(fd/Z5d0e ed#e e(de(fd1Z6 dBd2e ed3ed#e e(d4e)d(e ededefd5Z7d6e(d7e e"de(fd8Z8Gd9d:Z9d;e defd<Z:ed!d!d!d!d=de(deee fd7eee"dfde)ded e#dede9fd>Z;ed!d!d!d!d=deee fdeee ee"fd7eee"dfde)ded e#dede9fd?Z;ddddd=dee(ee fdeee ee"fd7eee"dfde)ded e#dede9fd@Z;y)Cz;Contains the primary optimization and contraction routines.)Decimal) lru_cache) Any CollectionDictIterableListLiteralOptionalSequenceTupleUnionoverload)backendsblashelpersparserpathssharing)ArrayIndexType ArrayShaped ArrayType BackendTypeContractionListType OptimizeKindPathTypeTensorShapeType) contract_pathcontractformat_const_einsum_strContractExpression shape_onlyN max_inputcbeZdZdZdedededededee de d e d ee d e ee ffd Z d efdZ y)PathInfozCA printable object to contain information about a contraction path.contraction_listinput_subscriptsoutput_subscriptindicespath scale_list naive_costopt_cost size_list size_dictc  ||_||_||_||_||_||_t ||_t ||_|jt|jt dz |_ | |_ |_ |jdD cgc]} t fd| Dc} |_|d||_t t| d|_ycc} w)N,c3(K|] }| ywN).0kr/s C/home/dcms/DCMS/lib/python3.12/site-packages/opt_einsum/contract.py z$PathInfo.__init__..<s6aYq\6s->default)r&r'r(r*r)r+rr,r-maxspeedupr.r/splittupleshapeseqlargest_intermediate) selfr&r'r(r)r*r+r,r-r.r/kss ` r8__init__zPathInfo.__init__#s!1 0 0  $!*-) T]]GAJ)GG ""AQAWAWX[A\]2u6266] %&b)9(:;$+C 1,E$F!^sC)returnc d}d|jddt|jddt|jddd|j d dd |j d dd |jd dd |jd d ddj|dg }t|jD]\}}|\}}}}}|"dj|dz|jz} nd} tddtdt|z } |j|||| | f} |jdj| dj|S)N)scalingBLAScurrent remainingz Complete contraction:  z Naive scaling: z Optimized scaling: rr;z Naive FLOP count: z.3ez Optimized FLOP count: z Theoretical speedup: z Largest intermediate: z elements zQ-------------------------------------------------------------------------------- z{:>6} {:>11} {:>22} {:>37} zP--------------------------------------------------------------------------------r2r:z...8z {:>4} {:>14} {:>22} {:>{}})rBlenr)r=r+r,r-r>rCformat enumerater&joinr(append) rDheader path_printn contraction_ einsum_strrLdo_blas remaining_strsize_remainingpath_runs r8__repr__zPathInfo.__repr__@s{<(y 3'DLL(9':" ='DOOQ(G'H K'' SNA{3> 0Aq*i$ # 3d :T=R=R R %  BRZ)A$ABN" H   F?FFQ R! S$wwz""N) __name__ __module__ __qualname____doc__rstrrrr intrrFr`r5rar8r%r% sMG-GG G  G  GSMGGGC=GS>G:#####rar% memory_limitr.rGc|dk(r t|St|tr td|y|dkr|dk(rytdt |S)Nr#zCmemory_limit must be None, int, or the string Literal['max_input'].r1z)Memory limit must be larger than 0, or -1)r= isinstancerf ValueErrorrg)rhr.s r8_choose_memory_argrmfs]{"9~,$^__a 2 HI I | ra)ordercastingdtypeoutkwargsc |j}i}|jddx}dk7r||d<|jddx}dk7r||d<|jddx}||d<|jddx}||d<|j||S)z@Filters out default contract kwargs to pass to various backends.rnKrosaferpNrq)copypopupdate)rrretrnrorprqs r8_filter_einsum_defaultsrz|s [[]F)+CGS))c1G ::i00V; IGT**7G zz%&&3E JJv JraTF)use_blasoptimizerhrA subscriptsoperandsr{r|rAcyr4r5r}r{r|rhrAr~rrs r8rr!$racyr4r5rs r8rrrrac  |dus|d}|jdd}t|rtd|j|gt |z}t j ||\} } } | jd} | D cgc] } t| }} |r| }n"| D cgc]} t j| }} t| }t| jdd }i}t| D]\}}||}t|t|k7rtd | |d |d t|D]O\}}t||}||vr3||d k(r|||<&|d ||fvs0td|d|d||d|d |||<Q| | gzDcgc]}tj||}}t!||}t| }t#d|Dt|z dkD}tj$||||}|durt't)|g}nt+|t,t.j0fs|}na|dkrt't)|g}nFt+|t.j0r |||||}n t/j2|}|||||}g} g}!g}g}"t|D]\}}#t't5|#d}#tj6|#||}$|$\}%}}&}'tj$|'t9|&t|#|}(| j;|(|!j;t|'|j;tj|%||#D cgc]} | j| })} |#D cgc]} |j| }*} |r(t=j>|)d jA|%|&|*}+nd}+|t|z dk(r| },n7d jA|)}-d jAt5|%|-jB},t jD|)|*|,}.| j;|,|j;|.djA|)dz|,z}/t| dkr t'| }0nd}0|#|&|/|0|+f}1|"j;|1t#| }2|r| |"fStG|"| | |||!||2|| }3||3fScc} wcc} wcc}wcc} wcc} w)aFind a contraction order `path`, without performing the contraction. Parameters: subscripts: Specifies the subscripts for summation. *operands: These are the arrays for the operation. use_blas: Do you use BLAS for valid operations, may use extra memory for more intermediates. optimize: Choose the type of path the contraction will be optimized with. - if a list is given uses this as the path. - `'optimal'` An algorithm that explores all possible ways of contracting the listed tensors. Scales factorially with the number of terms in the contraction. - `'dp'` A faster (but essentially optimal) algorithm that uses dynamic programming to exhaustively search all contraction paths without outer-products. - `'greedy'` An cheap algorithm that heuristically chooses the best pairwise contraction at each step. Scales linearly in the number of terms in the contraction. - `'random-greedy'` Run a randomized version of the greedy algorithm 32 times and pick the best path. - `'random-greedy-128'` Run a randomized version of the greedy algorithm 128 times and pick the best path. - `'branch-all'` An algorithm like optimal but that restricts itself to searching 'likely' paths. Still scales factorially. - `'branch-2'` An even more restricted version of 'branch-all' that only searches the best two options at each step. Scales exponentially with the number of terms in the contraction. - `'auto'` Choose the best of the above algorithms whilst aiming to keep the path finding time below 1ms. - `'auto-hq'` Aim for a high quality contraction, choosing the best of the above algorithms whilst aiming to keep the path finding time below 1sec. memory_limit: Give the upper bound of the largest intermediate tensor contract will build. - None or -1 means there is no limit - `max_input` means the limit is set as largest input tensor - a positive integer is taken as an explicit limit on the number of elements The default is None. Note that imposing a limit can make contractions exponentially slower to perform. shapes: Whether ``contract_path`` should assume arrays (the default) or array shapes have been supplied. Returns: path: The optimized einsum contraciton path PathInfo: A printable object containing various information about the path found. Notes: The resulting path indicates which terms of the input contraction should be contracted first, the result of this contraction is then appended to the end of the contraction list. Examples: We can begin with a chain dot example. In this case, it is optimal to contract the b and c tensors represented by the first element of the path (1, 2). The resulting tensor is added to the end of the contraction and the remaining contraction, `(0, 1)`, is then executed. ```python a = np.random.rand(2, 2) b = np.random.rand(2, 5) c = np.random.rand(5, 2) path_info = opt_einsum.contract_path('ij,jk,kl->il', a, b, c) print(path_info[0]) #> [(1, 2), (0, 1)] print(path_info[1]) #> Complete contraction: ij,jk,kl->il #> Naive scaling: 4 #> Optimized scaling: 3 #> Naive FLOP count: 1.600e+02 #> Optimized FLOP count: 5.600e+01 #> Theoretical speedup: 2.857 #> Largest intermediate: 4.000e+00 elements #> ------------------------------------------------------------------------- #> scaling current remaining #> ------------------------------------------------------------------------- #> 3 kl,jk->jl ij,jl->il #> 3 jl,ij->il il->il ``` A more complex index transformation example. ```python I = np.random.rand(10, 10, 10, 10) C = np.random.rand(10, 10) path_info = oe.contract_path('ea,fb,abcd,gc,hd->efgh', C, C, I, C, C) print(path_info[0]) #> [(0, 2), (0, 3), (0, 2), (0, 1)] print(path_info[1]) #> Complete contraction: ea,fb,abcd,gc,hd->efgh #> Naive scaling: 8 #> Optimized scaling: 5 #> Naive FLOP count: 8.000e+08 #> Optimized FLOP count: 8.000e+05 #> Theoretical speedup: 1000.000 #> Largest intermediate: 1.000e+04 elements #> -------------------------------------------------------------------------- #> scaling current remaining #> -------------------------------------------------------------------------- #> 5 abcd,ea->bcde fb,gc,hd,bcde->efgh #> 5 bcde,fb->cdef gc,hd,cdef->efgh #> 5 cdef,gc->defg hd,defg->efgh #> 5 defg,hd->efgh efgh->efgh ``` TNauto einsum_callFz)Did not understand the following kwargs: )rAr2rPzEinstein sum subscript 'z=' does not contain the correct number of indices for operand .r1zSize of label 'z' for operand z (z!) does not match previous terms (z).c32K|]}t|ywr4)rQr6xs r8r9z contract_path..Ts4AQ4sr)reverserj)keyr:)$rwrQ TypeErrorkeyslistrparse_einsum_inputr? frozenset get_shapereplacerSrlrgrcompute_size_by_dictrmsum flop_countr@rangerkrfr PathOptimizer get_path_fnsortedfind_contractionboolrUrcan_blasrTfindfind_output_shaper%)4r}r{r|rhrAr~rreinsum_call_arg operands_r'r(operands_prepped input_listr input_sets input_shapes output_setr)r/tnumtermshcnumchardimr. memory_argnum_ops inner_productr, path_tuplepath_optimizer cost_listr+r& contract_indscontract_tupleout_inds idx_removed idx_contractcost tmp_inputs tmp_shapesr\ idx_resultall_input_inds shp_resultr[rLrYr-rWs4 r8rrsAd Dh.jj6O 6{CFKKM?STT tH~-I;A;T;TU^gm;n8&(8"'',J(231)A,3J3 ' 5EF((+F F+,J(00b9:G!#I +& d $  r7c$i *:d+;*<=99=aA $D/ &JD$bh-Cy T?a'&)IdOIdO 44$)$~dV2iPToEVW""%b* #& $ &&0LVYiXjKjk4--dI>kIk#L)?AjnnQ'? ?3@Aal&&q)A A mmJ0A;PZ[GG 3z? "r ))J WWZ0Nn6I6I!JKJ--j*jQ *%J'XXj)D0:=  z?b 383DII$k:y'R  ,Y,-\9~H!111 J z !!G4G<l\@AsSS  S&SScXtjd|jdd}t|dts||i|S|d|dd}}t j |s4d|vr|dt j|zz }t j|}t|}||g|i|S)zJBase einsum, but with pre-parse for valid characters if a string is given.einsumbackendnumpyrr1Nr:) rget_funcrwrkrfrhas_valid_einsum_chars_onlyfind_output_strconvert_to_valid_einsum_charsrz)r~rrfnr[s r8_einsumrs   8VZZ 7%C DB hqk3 '8&v&&#A; J  - -j 9 z ! $!7!7 !CC CJ99*E $V ,F j .8 .v ..raraxes.c$|j|Sr4) transpose)rrs r8_default_transposers ;;t rarcJtjd|t}|||S)zBase transpose.r)rrr)rrrrs r8 _transposers%   ;1C DB a;raycDtjd|}||||S)zBase tensordot. tensordot)r)rr)rrrrrs r8 _tensordotrs%   ; 0B a ra)rqr{r|rhrrqcyr4r5r}rqr{r|rhrr~rrs r8rrracyr4r5rs r8rrrrarc |dus|d}|gt|z}|dur t|d|i|S|jdd} |jdi} | r|d} t|||d|d\}} | rt  | | fi|St || f||d |S) a0Evaluates the Einstein summation convention on the operands. A drop in replacement for NumPy's einsum function that optimizes the order of contraction to reduce overall scaling at the cost of several intermediate arrays. Parameters: subscripts: Specifies the subscripts for summation. *operands: These are the arrays for the operation. out: A output array in which set the resulting output. use_blas: Do you use BLAS for valid operations, may use extra memory for more intermediates. optimize:- Choose the type of path the contraction will be optimized with - if a list is given uses this as the path. - `'optimal'` An algorithm that explores all possible ways of contracting the listed tensors. Scales factorially with the number of terms in the contraction. - `'dp'` A faster (but essentially optimal) algorithm that uses dynamic programming to exhaustively search all contraction paths without outer-products. - `'greedy'` An cheap algorithm that heuristically chooses the best pairwise contraction at each step. Scales linearly in the number of terms in the contraction. - `'random-greedy'` Run a randomized version of the greedy algorithm 32 times and pick the best path. - `'random-greedy-128'` Run a randomized version of the greedy algorithm 128 times and pick the best path. - `'branch-all'` An algorithm like optimal but that restricts itself to searching 'likely' paths. Still scales factorially. - `'branch-2'` An even more restricted version of 'branch-all' that only searches the best two options at each step. Scales exponentially with the number of terms in the contraction. - `'auto', None, True` Choose the best of the above algorithms whilst aiming to keep the path finding time below 1ms. - `'auto-hq'` Aim for a high quality contraction, choosing the best of the above algorithms whilst aiming to keep the path finding time below 1sec. - `False` will not optimize the contraction. memory_limit:- Give the upper bound of the largest intermediate tensor contract will build. - None or -1 means there is no limit. - `max_input` means the limit is set as largest input tensor. - A positive integer is taken as an explicit limit on the number of elements. The default is None. Note that imposing a limit can make contractions exponentially slower to perform. backend: Which library to use to perform the required ``tensordot``, ``transpose`` and ``einsum`` calls. Should match the types of arrays supplied, See `contract_expression` for generating expressions which convert numpy arrays to and from the backend library automatically. Returns: The result of the einsum expression. Notes: This function should produce a result identical to that of NumPy's einsum function. The primary difference is ``contract`` will attempt to form intermediates which reduce the overall scaling of the given einsum contraction. By default the worst intermediate formed will be equal to that of the largest input array. For large einsum expressions with many input arrays this can provide arbitrarily large (1000 fold+) speed improvements. For contractions with just two tensors this function will attempt to use NumPy's built-in BLAS functionality to ensure that the given operation is performed optimally. When NumPy is linked to a threaded BLAS, potential speedups are on the order of 20-100 for a six core machine. TrFrq_gen_expression_constants_dictr)r|rhrr{rrq)rrrwrr!_core_contract) r}rqr{r|rhrr~rr operands_listgen_expressionconstants_dictfull_strr&s r8rrsV Dh.L4>1M5 939&99ZZ 159NZZ 126N #"/  RVai"H !(,|jjddS)Nrr)rcr?)rs r8_infer_backend_class_cachedr^s >>   $Q ''rac,t|jSr4)r __class__)rs r8 infer_backendrcs &q{{ 33raarraysc`|dk7r||St|d}tj|sy|S)zuFind out what backend we should use, dipatching based on the first array if ``backend='auto'`` is specified. rrr)rr has_tensordot)rrs r8 parse_backendrgs< 6 3F1I&G  ! !' * Nrarr&evaluate_constantsc |du}t|t|}tj| }t |D]\}} | \} } } } |rt fd| Dr ||dfcS| Dcgc]}j |}}|xr|dzt|k(}| r d| vs|r| jd\}}|jd\}}djfd||zD}rpgg}}D]B}|j|j||j|j|Dtttt||}nd }t|||d |}||k7s|rMtt!|j"|}t%||| }|r||ddnd}|r|}t'| g|||d |}j|~~|r|Sd Scc}w) zInner loop used to perform an actual contraction given the output from a ``contract_path(..., einsum_call=True)`` call. Nc3,K|] }|du ywr4r5)r6rr~s r8r9z!_core_contract..s%HahqkT&9%Hsr1EINSUMr:r2rPc3,K|] }|vs| ywr4r5)r6sidx_rms r8r9z!_core_contract..s#[!1TZ?A#[s )r5r5)rrrr)rrr has_einsumrSanyrwrQr?rTrUrr@ziprrmapindexrr)rr&rrrqrr specified_out no_einsumnumrYindsr[rZ blas_flagr tmp_operands handle_out input_str results_index input_left input_right tensor_resultleft_pos right_posrrnew_viewr out_kwargrr~s @@r8rrws'tOMIHHg.G''00I&&676#[1<.fj!Y #%H4%H"H-cd33 3156A Q6 6#KqS9I5J(J  ()3y'1'7'7'= $I}&/ooc&: #J GG#[zK/G#[[M&("):AOOJOOA$67$$[%5%5a%89: S&Xy)A"BCD ">> format_const_einsum_str('ab,bc,cd->ad', [0, 2]) 'bc,[ab,cd]->ad' No-op if there are no constants. r:rPr2[]z{}{}{}z],[)r?rSrRrTr) r[rlhsrhsarrowit wrapped_termsformatted_einsum_strs r8r r s  z##D)S$b"%SCLSYYWZ^C\]41aiq1XQ6]M]#??388M+BE3O077sC  ^sBc *eZdZdZdededeeefde fdZ dde ed d fd Z ded e e efd Zd eeded e fdZ dd eede ede eded ef dZ dd eede ededed ef dZd dddd eded efdeded ef dZd efdZd efdZy )r!zHelper class for storing an explicit ``contraction_list`` which can then be repeatedly called solely with the array arguments. rYr&rrrc t||j|_||_||_|j ddz|_|j t|z |_||_ ||_ i|_ i|_ y)Nr2r1) r rrYr&rrcount_full_num_argsrQnum_args_full_contraction_listr_evaluated_constants_backend_expressions)rDrYr&rrrs r8rFzContractExpression.__init__s~3;@S@S@UV 0 *//4q8++c..AA '7#-46!46!rarrrGNc6t|jDcgc]}|jj|d }}t ||} t j |||\}}||j|<||_ ycc}w#t$r|||dd\}}Y3wxYw)aFConvert any constant operands to the correct backend form, and perform as many contractions as possible to create a new list of operands, stored in ``self._evaluated_constants[backend]``. This also makes sure ``self.contraction_list`` only contains the remaining, non-const operations. NT)rr) rrrgetrrrKeyErrorrr&)rDrr  tmp_const_opsnew_opsnew_contraction_lists r8rz%ContractExpression.evaluate_constantssEJ$J]J]D^_q--11!T:_ _ w7 k,4,G,GQ^`d,e )G).5!!'* 4`  k,0-ei,j )G) ks#A; BBBc |j|S#t$r#|j||j|cYSwxYw)zRetrieve or generate the cached list of constant operators (mixed in with None representing non-consts) and the remaining contraction list. )rrr)rDrs r8_get_evaluated_constantsz+ContractExpression._get_evaluated_constantssF  6,,W5 5 6  # #G ,,,W5 5 6s )==rc |j|S#t$r+tj|||}||j|<|cYSwxYwr4)rrrbuild_expression)rDrrrs r8_get_backend_expressionz*ContractExpression._get_backend_expressionsP ,,W5 5 **7FDAB13D % %g .I s1AAFrqrc~|r |jn |j}tt||f|||d|jS)zThe normal, core contraction.rqrr)rr&rrrr)rDrrqrrr&s r8 _contractzContractExpression._contract&sQ;M466RVRgRg L  1  kk   ract|rtj|||S|j|||}|||d<|S|S)aSpecial contraction, i.e., contraction with a different backend but converting to and from that backend. Retrieves or generates a cached expression using ``arrays`` as templates, then calls it with ``arrays``. If ``evaluate_constants=True``, perform a partial contraction that prepares the constant tensors and operations with the right backend. r5)rrr#)rDrrqrrresults r8_contract_with_conversionz,ContractExpression._contract_with_conversion9sM ..wE E>--fg>G ?CGJ rar%czt||}|r |jn |j}t||k7r%t d|jdt|d|j r;|s9t ||j|}}|Dcgc]}| t|n|} }n|} tj|r'td|Dr|j| |||S|j| |||Scc}w#t$r7} | jrt| jnd} d | d f} | | _d} ~ wwxYw) a(Evaluate this expression with a set of arrays. Parameters: arrays: The arrays to supply as input to the expression. out: If specified, output the result into this array. backend: Perform the contraction with this backend library. If numpy arrays are supplied then try to convert them to and from the correct backend array type. evaluate_constants: Pre-evaluates constants with the appropriate backend. Returns: The contracted result. z(This `ContractExpression` takes exactly z array arguments but received rNc38K|]}t|dk(yw)rN)rrs r8r9z.ContractExpression.__call__..|s4aUV]15E5P4as)rr%rPzInternal error while evaluating `ContractExpression`. Note that few checks are performed - the number and rank of the array arguments must match the original expression. The internal error was: '')rrrrQrlriterr nextr has_backendallr)r&argsrf) rDrqrrrcorrect_num_argsops_var ops_constopopserr original_msgmsgs r8__call__zContractExpression.__call__TsR( 02D4..$-- v;* *:4==/J #F }A/    (:!%ft/L/LW/UYGV_'`PRW (K'`C'`C ##G,4aZ`4a1a55c3\n5oo>>#3Tf>g g(a ,/HH3sxx="L,,8><C CH  s$C5$;C: C:: D:2D55D:cv|jrdt|j}nd}d|jd|dS)Nz , constants=rPz)rrrY)rDconstants_reprs r8r`zContractExpression.__repr__sE   +F43G3G,H+IJNN&t'7'7&8.9ILLrac>|jg}t|jD]d\}}|jd|dzd|jd|dd|dr d|ddnd z|jd |jfd j |S) Nz r1z. r,rrjz [r rPz einsum_kwargs=)r`rSr&rUrrrT)rDrr cs r8__str__zContractExpression.__str__s ]]_ d334 7DAq HHtAE7#& ' HHq1a[QrUb2qMC D HH' }5 6 7wwqzra)r)NrF)F)rbrcrdrerfrrrgrrrFr rr r r r#rr&r)rr:r`r?r5rar8r!r!s77.7S)^, 7  7,5(3-5T5( 6 6Xi=P8Q 6hy.ACTW$(!'#(  # i  #  !    0$) #i   !   <'+#( 554? #5 5 ! 5  5nM#Mrar!shapect|S)z^Dummy ``numpy.ndarray`` which has a shape only - for generating contract expressions. )r)r@s r8r"r"s u ra)rr{r|rhcyr4r5r}rr{r|rhr~rrs r8contract_expressionrDracyr4r5rCs r8rDrDrErac|s tddD]#}|j|dtd|dt|tst j |f|z\}}d|d<|xsd}|Dcic]}||| } }| |d <t |D cgc]\}} ||vr| n t| } }} t|g| |||d |Scc}wcc} }w) a>Generate a reusable expression for a given contraction with specific shapes, which can, for example, be cached. Parameters: subscripts: Specifies the subscripts for summation. shapes: Shapes of the arrays to optimize the contraction for. constants: The indices of any constant arguments in `shapes`, in which case the actual array should be supplied at that position rather than just a shape. If these are specified, then constant parts of the contraction between calls will be reused. Additionally, if a GPU-enabled backend is used for example, then the constant tensors will be kept on the GPU, minimizing transfers. kwargs: Passed on to `contract_path` or `einsum`. See `contract`. Returns: Callable with signature `expr(*arrays, out=None, backend='numpy')` where the array's shapes should match `shapes`. Notes: The `out` keyword argument should be supplied to the generated expression rather than this function. The `backend` keyword argument should also be supplied to the generated expression. If numpy arrays are supplied, if possible they will be converted to and back from the correct backend array type. The generated expression will work with any arrays which have the same rank (number of dimensions) as the original shapes, however, if the actual sizes are different, the expression may no longer be optimal. Constant operations will be computed upon the first call with a particular backend, then subsequently reused. Examples: Basic usage: ```python expr = contract_expression("ab,bc->ac", (3, 4), (4, 5)) a, b = np.random.rand(3, 4), np.random.rand(4, 5) c = expr(a, b) np.allclose(c, a @ b) #> True ``` Supply `a` as a constant: ```python expr = contract_expression("ab,bc->ac", a, (4, 5), constants=[0]) expr #> ac', constants=[0])> c = expr(b) np.allclose(c, a @ b) #> True ``` z9Can only generate expressions for optimized contractions.)rqrNr,zU' should only be specified when calling a `ContractExpression`, not when building it.Trr5r)r{r|rh) rlrrkrfrconvert_interleaved_inputrSr"r) r}rr{r|rhrArrargr rr dummy_arrayss r8rDrDs~ TUU! ::c4 ,C5qq  j# &#==zmf>TU F $F RI,56qal6N6 .F HQQWGXYtq!iAZ]:YLY  ! ,4xVb fl  7Zs 1 CC )r)rFN)rWsPAmmmmFF    T3)==> C#C#L\d3iHUXM&?@D);S)@$AdK]_bKbFc* !!% $$$$ $  $  $$ 8X $ $ !!% $$Y 3/0$$ $  $  $$ 8X $ $!!% C"C"C"C" C"  C"  C"C" 8X C"L /s/c/i//*)5c?y  )5c?Sy  ) sCx3]f  !$                 !$  Y 3/0              $!!%!eZc9n%eZY 3/0eZ ) eZ eZ  eZ  eZeZeZeZP 4(T(c((4S4S4 (9-  # &$$# P "P)Pc]P P )  P  PPf    # 4ttno+ /2 !$ Y/0Z_d*+       /2 !$ i01YC@AZ_d*+      /3!!% Wc9o56W 9oz#> ?WZ_d*+W W  W  WWWra