Repository navigation
Expand file tree
/
Copy pathNDExpr.Evaluate.cs
More file actions
1884 lines (1652 loc) · 109 KB
/
Copy pathNDExpr.Evaluate.cs
File metadata and controls
1884 lines (1652 loc) · 109 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
using System;
using System.Collections.Generic;
using System.Reflection.Emit;
using System.Text;
using NumSharp.Backends.Kernels;
// =============================================================================
// NDExpr.Evaluate.cs — np.evaluate surface of the expression DSL (Wave 6.1)
// =============================================================================
//
// Adds the pieces that turn the Tier-3C compiler into a user-facing fused
// evaluator:
//
// • ArrayNode — an NDArray embedded directly as a leaf, so trees read
// naturally: (NDExpr)a * b + 2. np.evaluate REBINDS array leaves to
// positional InputNodes, deduplicating repeated references — the same
// NDArray instance appearing twice becomes ONE iterator operand
// ((a-b)/(a+b) iterates 3 streams, not 5).
// • implicit conversions NDArray→NDExpr and numeric→Const, so a single
// cast at the head of an expression lights up the whole operator set.
// • ReduceNode — root-only fused reductions (sum/prod/min/max/mean of an
// arbitrary elementwise tree) compiled to a one-pass accumulating
// kernel: sum(a*b) reads a and b once and never materializes a*b.
//
// Binding is a pure rewrite: nodes are immutable, so BindArrays returns the
// same instance when no array leaf lives below a node, or a rebuilt node
// otherwise. The bound tree is what typing + emission consume.
// =============================================================================
namespace NumSharp.Backends.Iteration
{
/// <summary>Reduction kinds supported by <see cref="ReduceNode"/>.</summary>
/// <remarks>
/// <see cref="Any"/> / <see cref="All"/> are their OWN kinds, not <see cref="Max"/> / <see cref="Min"/>
/// over a boolean child: <c>logical_or</c> / <c>logical_and</c> carry the identities <c>False</c> /
/// <c>True</c>, so a reduction over an EMPTY input is <c>False</c> / <c>True</c> — where
/// <c>maximum.reduce</c> / <c>minimum.reduce</c> raise "zero-size array … which has no identity". They
/// also return <c>bool</c> where a bool <see cref="Sum"/> would widen to int64. The value fold is a
/// bitwise OR / AND on a bool accumulator, which is associative AND idempotent — so the 4-accumulator
/// unroll reorders it freely and stays bit-exact (unlike float <see cref="Sum"/> / <see cref="Prod"/>,
/// whose order matters — the M1/M2 divert).
/// </remarks>
public enum NDExprReduceKind : byte
{
Sum,
Prod,
Min,
Max,
Mean,
/// <summary><c>logical_or.reduce</c> of the nonzero-test of the child (identity <c>False</c>; bool result).</summary>
Any,
/// <summary><c>logical_and.reduce</c> of the nonzero-test of the child (identity <c>True</c>; bool result).</summary>
All,
/// <summary>
/// <c>np.ptp</c> — peak-to-peak (<c>max - min</c>) of the child. Result dtype is the child's
/// (integer/unsigned overflow WRAPS exactly as NumPy's, since it is a plain subtract of two
/// same-dtype reductions), a NaN in the child propagates to the result, and there is NO empty
/// identity (a zero-size input raises, like <see cref="Max"/>/<see cref="Min"/>). Unlike the
/// fold-driven kinds above it is host-delegated: <see cref="np.ptp(NDArray,NDAxis?,NDArray,bool)"/>
/// runs over the materialized child — see the host divert in <c>DefaultEngine.EvaluateReduce</c>.
/// </summary>
Ptp,
/// <summary>
/// <c>np.nanmin</c> — minimum ignoring NaN. Result dtype is the child's; a float/complex child
/// has its NaNs skipped (an ALL-NaN input yields NaN, matching NumPy's all-NaN-slice contract),
/// while an integer/bool child carries no NaN and folds as a plain minimum. Host-delegated to
/// <see cref="np.nanmin(NDArray,int?,NDArray,bool,object,NDArray)"/> over the materialized child, which is why it is
/// TYPE-AWARE for free (the ±inf NaN-replacement sentinel that would promote an int child to
/// float64 lives inside the engine reduction, not in an NDExpr rewrite).
/// </summary>
NanMin,
/// <summary>
/// <c>np.nanmax</c> — maximum ignoring NaN (the <see cref="NanMin"/> twin, all-NaN → NaN).
/// Host-delegated to <see cref="np.nanmax(NDArray,int?,NDArray,bool,object,NDArray)"/> over the materialized child.
/// </summary>
NanMax,
/// <summary>
/// <c>np.argmax</c> — the index of the maximum. Unlike every value reduction above, the result
/// dtype is <b>int64</b> (NumPy's <c>intp</c>), NOT the child dtype. It is host-delegated to
/// <see cref="np.argmax(NDArray,int,bool)"/> (flat: <see cref="np.argmax(NDArray)"/>) over the
/// materialized child. This is bit-exact for the same reason the M4-tail value kinds are —
/// but the property in play is subtler than order-independence: argmax's index DOES depend on
/// visiting order at a tie (the FIRST maximum wins, and a NaN is treated as the largest so the
/// FIRST NaN wins), yet the materialized child is a fresh C-CONTIGUOUS buffer holding exactly
/// NumPy's own C-order intermediate, and <c>np.argmax</c> walks it in that same C-order — so the
/// tie/NaN index is deterministic and identical to <c>np.argmax(child)</c>. There is NO empty
/// identity (a zero-size input raises, like <see cref="Max"/>). See <c>EvaluateDelegatingReduce</c>.
/// </summary>
ArgMax,
/// <summary>
/// <c>np.argmin</c> — the index of the minimum (the <see cref="ArgMax"/> twin: int64 result,
/// first-tie / first-NaN wins over the C-order materialized child). Host-delegated to
/// <see cref="np.argmin(NDArray,int,bool)"/> / <see cref="np.argmin(NDArray)"/>.
/// </summary>
ArgMin,
/// <summary>
/// <c>np.nanmean</c> — the arithmetic mean with NaNs skipped (the <see cref="Mean"/> twin over
/// the finite elements). Result dtype follows <see cref="Mean"/> (float16→float16 via a float32
/// intermediate, float32→float32, float64→float64, complex128→complex128, int/bool→float64), an
/// ALL-NaN input yields NaN and an integer/bool child — carrying no NaN — is exactly <c>Mean</c>.
/// Unlike <see cref="Sum"/>/<see cref="Mean"/> it is NOT a fold kind and NOT a factory rewrite
/// (its per-element NaN skip changes the divisor per slab): the host materializes the child once
/// and computes <c>nansum(child) / count_of_non_NaN</c> with the SAME NumPy-exact pairwise sum the
/// M1/M2 diverts use — see <c>DefaultEngine.EvaluateStatReduce</c>. Bit-exact vs NumPy 2.4.2, so
/// it carries NO MisalignedRegistry excuse.
/// </summary>
NanMean,
/// <summary>
/// <c>np.var</c> — the variance <c>Σ(x−mean)² / (N−ddof)</c> (population variance at the default
/// <c>ddof=0</c>). Result dtype: float16→float16 (computed in float32), float32→float32,
/// float64→float64, int/bool→float64, and — like NumPy — a complex128 child yields a <b>real</b>
/// float64 variance (the deviations are reduced as <c>|x−mean|²</c>). A NaN anywhere PROPAGATES
/// (var uses every element, unlike <see cref="NanMean"/>); <c>ddof ≥ N</c> divides by a clamped
/// zero → <c>+inf</c> (or NaN when the numerator is zero), and an empty input yields NaN. The host
/// materializes the child once, then runs NumPy's own two-pass <c>_var</c> op for op over the
/// exact pairwise sum (mean, then <c>Σ(x−mean)²</c>) — see <c>DefaultEngine.EvaluateStatReduce</c>.
/// The degrees-of-freedom offset is carried on the node (<see cref="ReduceNode.Ddof"/>) and is
/// part of the program identity. Bit-exact vs NumPy 2.4.2, NO excuse.
/// </summary>
Var,
/// <summary>
/// <c>np.std</c> — the standard deviation <c>sqrt(var)</c> (the <see cref="Var"/> twin, same
/// result dtypes / ddof / NaN-propagation / empty→NaN semantics), applied as a final elementwise
/// square root over the variance so it is bit-exact wherever <see cref="Var"/> is.
/// </summary>
Std,
}
/// <summary>
/// Operand collection for binding array leaves: deduplicates by reference
/// so a repeated NDArray maps to one iterator operand.
/// </summary>
[NDBorrowed] // the operands an expression is bound over are the caller's arrays
internal sealed class NDExprBindContext
{
public readonly List<NDArray> Operands = new();
/// <summary>
/// A rewrite hook for a pass over an already-bound tree (null in ordinary binding): called by every
/// <see cref="BinaryNode"/> with the original node and its rewritten children, AFTER the children (so nested
/// nodes are rewritten first, in evaluation order); a non-null return replaces the node. The float fmax / fmin
/// staging (NDExpr.FMaxStages.cs) lowers those nodes into stage-result leaves through it.
/// </summary>
public Func<BinaryNode, NDExpr, NDExpr, NDExpr> BinaryRewrite;
/// <summary>
/// A rewrite hook for positional leaves (null in ordinary binding): called by every <see cref="InputNode"/>; a
/// non-null return replaces the leaf. The fmax / fmin staging renumbers a child subtree's inputs through it, so
/// the child is evaluated over exactly the operands it reads.
/// </summary>
public Func<InputNode, NDExpr> InputRewrite;
/// <summary>
/// Set by a node that only a text plan runs (a numpy.strings function, <see cref="StringsNode"/>, or a cast to a text
/// dtype, <see cref="CastNode"/>) when it is bound: the program build then lowers the tree into stages even when no
/// input is text, so the stage gives NumPy's answer per call (<c>StrLen</c> over an int array raises NumPy's no-loop
/// error, <c>Cast(age, "U5")</c> formats the numbers) instead of a kernel build failing on a node that has no IL.
/// </summary>
public bool HoldsStageOnlyNode;
public int IndexOf(NDArray array)
{
for (int i = 0; i < Operands.Count; i++)
{
if (ReferenceEquals(Operands[i], array))
return i;
}
// A text leaf (S, U or StringDType) binds like any other: the program build lowers the nodes that compute on
// it into stages (NDExpr.Text.cs), so the fused kernel itself only ever sees numbers.
Operands.Add(array);
return Operands.Count - 1;
}
}
public abstract partial class NDExpr
{
// ===================================================================
// Array leaves + literal sugar
// ===================================================================
/// <summary>
/// Embed an NDArray directly as an expression leaf. np.evaluate binds
/// every distinct array (by reference) to one iterator operand.
/// </summary>
public static NDExpr Arr(NDArray array) => new ArrayNode(array);
public static implicit operator NDExpr(NDArray array) => new ArrayNode(array);
public static implicit operator NDExpr(double value) => Const(value);
public static implicit operator NDExpr(float value) => Const(value);
public static implicit operator NDExpr(int value) => Const(value);
public static implicit operator NDExpr(long value) => Const(value);
public static implicit operator NDExpr(uint value) => Const(value);
public static implicit operator NDExpr(ulong value) => Const(value);
public static implicit operator NDExpr(bool value) => Const(value);
public static implicit operator NDExpr(System.Numerics.Complex value) => Const(value);
public static implicit operator NDExpr(Half value) => Const(value);
public static implicit operator NDExpr(decimal value) => Const(value);
// Mixed NDExpr/NDArray operators. Exact-match overloads are required:
// through implicit conversions alone, `expr * ndarray` is ambiguous
// between NDExpr.op_*(NDExpr, NDExpr) and NDArray's own
// object-accepting operator overloads.
public static NDExpr operator +(NDExpr a, NDArray b) => Add(a, Arr(b));
public static NDExpr operator +(NDArray a, NDExpr b) => Add(Arr(a), b);
public static NDExpr operator -(NDExpr a, NDArray b) => Subtract(a, Arr(b));
public static NDExpr operator -(NDArray a, NDExpr b) => Subtract(Arr(a), b);
public static NDExpr operator *(NDExpr a, NDArray b) => Multiply(a, Arr(b));
public static NDExpr operator *(NDArray a, NDExpr b) => Multiply(Arr(a), b);
public static NDExpr operator /(NDExpr a, NDArray b) => Divide(a, Arr(b));
public static NDExpr operator /(NDArray a, NDExpr b) => Divide(Arr(a), b);
public static NDExpr operator %(NDExpr a, NDArray b) => Mod(a, Arr(b));
public static NDExpr operator %(NDArray a, NDExpr b) => Mod(Arr(a), b);
public static NDExpr operator &(NDExpr a, NDArray b) => BitwiseAnd(a, Arr(b));
public static NDExpr operator &(NDArray a, NDExpr b) => BitwiseAnd(Arr(a), b);
public static NDExpr operator |(NDExpr a, NDArray b) => BitwiseOr(a, Arr(b));
public static NDExpr operator |(NDArray a, NDExpr b) => BitwiseOr(Arr(a), b);
public static NDExpr operator ^(NDExpr a, NDArray b) => BitwiseXor(a, Arr(b));
public static NDExpr operator ^(NDArray a, NDExpr b) => BitwiseXor(Arr(a), b);
// Scalar operators. Also required as exact matches: without them a
// literal binds to the (NDExpr, NDArray) overload through NDArray's
// implicit numeric conversions (NDArray is the better conversion
// target because NDArray→NDExpr exists), silently turning a WEAK
// NEP50 literal into a strong scalar array — f4+2.5 would promote to
// f8 instead of staying f4.
public static NDExpr operator +(NDExpr a, double b) => Add(a, Const(b));
public static NDExpr operator +(double a, NDExpr b) => Add(Const(a), b);
public static NDExpr operator +(NDExpr a, long b) => Add(a, Const(b));
public static NDExpr operator +(long a, NDExpr b) => Add(Const(a), b);
public static NDExpr operator +(NDExpr a, int b) => Add(a, Const(b));
public static NDExpr operator +(int a, NDExpr b) => Add(Const(a), b);
public static NDExpr operator -(NDExpr a, double b) => Subtract(a, Const(b));
public static NDExpr operator -(double a, NDExpr b) => Subtract(Const(a), b);
public static NDExpr operator -(NDExpr a, long b) => Subtract(a, Const(b));
public static NDExpr operator -(long a, NDExpr b) => Subtract(Const(a), b);
public static NDExpr operator -(NDExpr a, int b) => Subtract(a, Const(b));
public static NDExpr operator -(int a, NDExpr b) => Subtract(Const(a), b);
public static NDExpr operator *(NDExpr a, double b) => Multiply(a, Const(b));
public static NDExpr operator *(double a, NDExpr b) => Multiply(Const(a), b);
public static NDExpr operator *(NDExpr a, long b) => Multiply(a, Const(b));
public static NDExpr operator *(long a, NDExpr b) => Multiply(Const(a), b);
public static NDExpr operator *(NDExpr a, int b) => Multiply(a, Const(b));
public static NDExpr operator *(int a, NDExpr b) => Multiply(Const(a), b);
public static NDExpr operator /(NDExpr a, double b) => Divide(a, Const(b));
public static NDExpr operator /(double a, NDExpr b) => Divide(Const(a), b);
public static NDExpr operator /(NDExpr a, long b) => Divide(a, Const(b));
public static NDExpr operator /(long a, NDExpr b) => Divide(Const(a), b);
public static NDExpr operator /(NDExpr a, int b) => Divide(a, Const(b));
public static NDExpr operator /(int a, NDExpr b) => Divide(Const(a), b);
public static NDExpr operator %(NDExpr a, double b) => Mod(a, Const(b));
public static NDExpr operator %(double a, NDExpr b) => Mod(Const(a), b);
public static NDExpr operator %(NDExpr a, long b) => Mod(a, Const(b));
public static NDExpr operator %(long a, NDExpr b) => Mod(Const(a), b);
public static NDExpr operator %(NDExpr a, int b) => Mod(a, Const(b));
public static NDExpr operator %(int a, NDExpr b) => Mod(Const(a), b);
public static NDExpr operator &(NDExpr a, long b) => BitwiseAnd(a, Const(b));
public static NDExpr operator &(long a, NDExpr b) => BitwiseAnd(Const(a), b);
public static NDExpr operator &(NDExpr a, int b) => BitwiseAnd(a, Const(b));
public static NDExpr operator &(int a, NDExpr b) => BitwiseAnd(Const(a), b);
public static NDExpr operator |(NDExpr a, long b) => BitwiseOr(a, Const(b));
public static NDExpr operator |(long a, NDExpr b) => BitwiseOr(Const(a), b);
public static NDExpr operator |(NDExpr a, int b) => BitwiseOr(a, Const(b));
public static NDExpr operator |(int a, NDExpr b) => BitwiseOr(Const(a), b);
public static NDExpr operator ^(NDExpr a, long b) => BitwiseXor(a, Const(b));
public static NDExpr operator ^(long a, NDExpr b) => BitwiseXor(Const(a), b);
public static NDExpr operator ^(NDExpr a, int b) => BitwiseXor(a, Const(b));
public static NDExpr operator ^(int a, NDExpr b) => BitwiseXor(Const(a), b);
// ulong: without an exact match a ulong literal has no implicit path to int/long and
// would bind through double — turning `u8 + 18446744073709551615UL` into a float64
// expression where NumPy keeps uint64 (and wraps). Complex: keeps the literal WEAK
// (a Complex→NDArray conversion would make it a strong 0-d array and cost an operand).
public static NDExpr operator +(NDExpr a, ulong b) => Add(a, Const(b));
public static NDExpr operator +(ulong a, NDExpr b) => Add(Const(a), b);
public static NDExpr operator -(NDExpr a, ulong b) => Subtract(a, Const(b));
public static NDExpr operator -(ulong a, NDExpr b) => Subtract(Const(a), b);
public static NDExpr operator *(NDExpr a, ulong b) => Multiply(a, Const(b));
public static NDExpr operator *(ulong a, NDExpr b) => Multiply(Const(a), b);
public static NDExpr operator /(NDExpr a, ulong b) => Divide(a, Const(b));
public static NDExpr operator /(ulong a, NDExpr b) => Divide(Const(a), b);
public static NDExpr operator %(NDExpr a, ulong b) => Mod(a, Const(b));
public static NDExpr operator %(ulong a, NDExpr b) => Mod(Const(a), b);
public static NDExpr operator &(NDExpr a, ulong b) => BitwiseAnd(a, Const(b));
public static NDExpr operator &(ulong a, NDExpr b) => BitwiseAnd(Const(a), b);
public static NDExpr operator |(NDExpr a, ulong b) => BitwiseOr(a, Const(b));
public static NDExpr operator |(ulong a, NDExpr b) => BitwiseOr(Const(a), b);
public static NDExpr operator ^(NDExpr a, ulong b) => BitwiseXor(a, Const(b));
public static NDExpr operator ^(ulong a, NDExpr b) => BitwiseXor(Const(a), b);
public static NDExpr operator +(NDExpr a, System.Numerics.Complex b) => Add(a, Const(b));
public static NDExpr operator +(System.Numerics.Complex a, NDExpr b) => Add(Const(a), b);
public static NDExpr operator -(NDExpr a, System.Numerics.Complex b) => Subtract(a, Const(b));
public static NDExpr operator -(System.Numerics.Complex a, NDExpr b) => Subtract(Const(a), b);
public static NDExpr operator *(NDExpr a, System.Numerics.Complex b) => Multiply(a, Const(b));
public static NDExpr operator *(System.Numerics.Complex a, NDExpr b) => Multiply(Const(a), b);
public static NDExpr operator /(NDExpr a, System.Numerics.Complex b) => Divide(a, Const(b));
public static NDExpr operator /(System.Numerics.Complex a, NDExpr b) => Divide(Const(a), b);
// Half / decimal: System.Numerics.Complex declares implicit conversions from BOTH (as from
// every primitive), and Complex converts implicitly to NDExpr, so without an exact match the
// Complex overloads above would capture `expr + (Half)2` and `expr + 0.1m` and type them
// complex. The exact overloads keep them the STRONG float16 / decimal scalars they are.
public static NDExpr operator +(NDExpr a, Half b) => Add(a, Const(b));
public static NDExpr operator +(Half a, NDExpr b) => Add(Const(a), b);
public static NDExpr operator -(NDExpr a, Half b) => Subtract(a, Const(b));
public static NDExpr operator -(Half a, NDExpr b) => Subtract(Const(a), b);
public static NDExpr operator *(NDExpr a, Half b) => Multiply(a, Const(b));
public static NDExpr operator *(Half a, NDExpr b) => Multiply(Const(a), b);
public static NDExpr operator /(NDExpr a, Half b) => Divide(a, Const(b));
public static NDExpr operator /(Half a, NDExpr b) => Divide(Const(a), b);
public static NDExpr operator +(NDExpr a, decimal b) => Add(a, Const(b));
public static NDExpr operator +(decimal a, NDExpr b) => Add(Const(a), b);
public static NDExpr operator -(NDExpr a, decimal b) => Subtract(a, Const(b));
public static NDExpr operator -(decimal a, NDExpr b) => Subtract(Const(a), b);
public static NDExpr operator *(NDExpr a, decimal b) => Multiply(a, Const(b));
public static NDExpr operator *(decimal a, NDExpr b) => Multiply(Const(a), b);
public static NDExpr operator /(NDExpr a, decimal b) => Divide(a, Const(b));
public static NDExpr operator /(decimal a, NDExpr b) => Divide(Const(a), b);
public static NDExpr operator %(NDExpr a, decimal b) => Mod(a, Const(b));
public static NDExpr operator %(decimal a, NDExpr b) => Mod(Const(a), b);
// bool: a WEAK Python bool (adopts any dtype); without the exact match it would bind through
// NDArray's bool conversion as a strong 0-d operand — same dtype, one more iterator stream.
public static NDExpr operator +(NDExpr a, bool b) => Add(a, Const(b));
public static NDExpr operator +(bool a, NDExpr b) => Add(Const(a), b);
public static NDExpr operator *(NDExpr a, bool b) => Multiply(a, Const(b));
public static NDExpr operator *(bool a, NDExpr b) => Multiply(Const(a), b);
public static NDExpr operator &(NDExpr a, bool b) => BitwiseAnd(a, Const(b));
public static NDExpr operator &(bool a, NDExpr b) => BitwiseAnd(Const(a), b);
public static NDExpr operator |(NDExpr a, bool b) => BitwiseOr(a, Const(b));
public static NDExpr operator |(bool a, NDExpr b) => BitwiseOr(Const(a), b);
public static NDExpr operator ^(NDExpr a, bool b) => BitwiseXor(a, Const(b));
public static NDExpr operator ^(bool a, NDExpr b) => BitwiseXor(Const(a), b);
// ===================================================================
// Reduction factories (root-only — see ReduceNode)
// ===================================================================
/// <summary>One-pass fused sum of the expression (NumPy dtype rules: int→int64, uint→uint64, floats preserved).</summary>
public static NDExpr Sum(NDExpr x) => new ReduceNode(NDExprReduceKind.Sum, x);
/// <summary>One-pass fused product of the expression.</summary>
public static NDExpr Prod(NDExpr x) => new ReduceNode(NDExprReduceKind.Prod, x);
/// <summary>One-pass fused minimum of the expression (NaN-propagating, like np.min).</summary>
public static NDExpr Min(NDExpr x) => new ReduceNode(NDExprReduceKind.Min, x);
/// <summary>One-pass fused maximum of the expression (NaN-propagating, like np.max).</summary>
public static NDExpr Max(NDExpr x) => new ReduceNode(NDExprReduceKind.Max, x);
/// <summary>One-pass fused arithmetic mean of the expression (ints→float64, floats preserved).</summary>
public static NDExpr Mean(NDExpr x) => new ReduceNode(NDExprReduceKind.Mean, x);
// --- axis-aware fused reductions (one pass, no intermediate; e.g. evaluate(Sum(a*b, axis:0))) ---
/// <summary>One-pass fused sum of the expression along <paramref name="axis"/>.</summary>
public static NDExpr Sum(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Sum, x, axis, keepdims);
/// <summary>One-pass fused product of the expression along <paramref name="axis"/>.</summary>
public static NDExpr Prod(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Prod, x, axis, keepdims);
/// <summary>One-pass fused minimum of the expression along <paramref name="axis"/> (NaN-propagating).</summary>
public static NDExpr Min(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Min, x, axis, keepdims);
/// <summary>One-pass fused maximum of the expression along <paramref name="axis"/> (NaN-propagating).</summary>
public static NDExpr Max(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Max, x, axis, keepdims);
/// <summary>One-pass fused arithmetic mean of the expression along <paramref name="axis"/>.</summary>
public static NDExpr Mean(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Mean, x, axis, keepdims);
// --- presence / count / NaN-aware reductions (plan P2 M4) --------------------------------
//
// Any/All are their OWN kinds (bool result, logical OR/AND fold, False/True identity — the empty
// input is False/True, not the "no identity" throw of max/min); the child is the nonzero-test
// x != 0 (ComparisonNode.TruthTest: flagged, because over text NumPy reads the truth value where a
// comparison with 0 has no loop), so the reduce just folds a bool stream. CountNonzero/NanSum/NanProd are pure
// COMPOSITIONS over the (M1/M2-exact) Sum/Prod, so they inherit flat+axis+bit-exactness for free:
// a rewrite is the whole implementation, no new kernel or host path.
/// <summary>
/// One-pass fused <c>np.any</c>: <c>True</c> iff any element of the expression is truthy
/// (nonzero). Result is <c>bool</c> and the identity is <c>False</c>, so <c>Any</c> of an EMPTY
/// input is <c>False</c> — unlike <see cref="Max(NDExpr)"/>, which raises on a zero-size input.
/// NaN is truthy (<c>nan != 0</c>), so <c>Any([nan])</c> is <c>True</c>, matching NumPy.
/// </summary>
public static NDExpr Any(NDExpr x) => new ReduceNode(NDExprReduceKind.Any, ComparisonNode.TruthTest(x));
/// <summary>
/// One-pass fused <c>np.all</c>: <c>True</c> iff every element of the expression is truthy
/// (nonzero). Result is <c>bool</c> and the identity is <c>True</c>, so <c>All</c> of an EMPTY
/// input is <c>True</c> (vacuous truth) — unlike <see cref="Min(NDExpr)"/>, which raises on a
/// zero-size input.
/// </summary>
public static NDExpr All(NDExpr x) => new ReduceNode(NDExprReduceKind.All, ComparisonNode.TruthTest(x));
/// <summary>
/// One-pass fused <c>np.count_nonzero</c>: the int64 count of truthy (nonzero) elements. Composed
/// as <c>Sum(x != 0)</c> — a sum over the bool nonzero-test — so the result is int64 (NumPy's
/// <c>intp</c>) at every child dtype, and an empty input counts to 0.
/// </summary>
public static NDExpr CountNonzero(NDExpr x) => new ReduceNode(NDExprReduceKind.Sum, ComparisonNode.TruthTest(x));
/// <summary>
/// One-pass fused <c>np.nansum</c>: the sum with NaNs treated as 0. Composed as
/// <c>Sum(Where(IsNaN(x), 0, x))</c>, so it is BIT-EXACT wherever the plain <see cref="Sum(NDExpr)"/>
/// is (float32/float64/complex via the M1 pairwise divert). An integer/bool child never carries a
/// NaN — <c>IsNaN</c> is all-false there and the <c>Where</c> passes the child through unchanged —
/// so <c>NanSum(int)</c> is exactly <c>Sum(int)</c> (int64), matching NumPy. An empty / all-NaN
/// input sums to 0. Over TEXT it is <c>np.nansum</c>'s own answer: NumPy's NaN replacement leaves a
/// string array as it is (a string dtype is not inexact), so the result is <c>np.sum</c>'s — a
/// StringDType concatenation, NumPy's <c>add.reduce</c> refusal for <c>S</c> / <c>U</c>.
/// </summary>
public static NDExpr NanSum(NDExpr x) => new ReduceNode(NDExprReduceKind.Sum, Where(IsNaN(x), Const(0), x), null, false, 0, nanFamily: true);
/// <summary>
/// One-pass fused <c>np.nanprod</c>: the product with NaNs treated as 1. Composed as
/// <c>Prod(Where(IsNaN(x), 1, x))</c> — bit-exact wherever the plain <see cref="Prod(NDExpr)"/> is
/// (float32/float64 via the M1 sequential divert), an identity pass-through for integer children,
/// and 1 for an empty / all-NaN input, matching NumPy. Over TEXT it is <c>np.nanprod</c>'s answer,
/// <c>np.prod</c>'s: NumPy's <c>multiply.reduce</c> refusal (no string loop multiplies two strings).
/// </summary>
public static NDExpr NanProd(NDExpr x) => new ReduceNode(NDExprReduceKind.Prod, Where(IsNaN(x), Const(1), x), null, false, 0, nanFamily: true);
// --- range / NaN-aware min-max reductions (plan P2 M4-tail) -------------------------------
//
// Unlike NanSum/NanProd these are NOT tree rewrites: they are their OWN kinds whose child is the
// RAW expression, because their semantics need machinery an NDExpr cannot carry. Ptp is two
// reductions (max - min) and cannot be spelled as one root reduce; NanMin/NanMax must be
// TYPE-AWARE (a float child's NaNs are replaced with the ±inf sentinel, an int child's are not —
// an NDExpr rewrite spelling `Where(IsNaN(x), +inf, x)` would promote every int child to float64,
// which NumPy does not). All three are ORDER-INDEPENDENT (min / max / their difference are the
// same whatever the summation order), so the host materializes the child once and reduces it
// through the already-NumPy-exact engine reduction (np.ptp / np.nanmin / np.nanmax) — bit-exact
// by construction, needing no pairwise divert and carrying no MisalignedRegistry excuse (unlike
// the summation kinds). See the host divert in DefaultEngine.EvaluateReduce.
/// <summary>
/// One-pass fused <c>np.ptp</c>: the peak-to-peak range <c>max - min</c> of the expression. The
/// result dtype is the child's, so integer/unsigned overflow WRAPS exactly as NumPy's does, and a
/// NaN anywhere in the child propagates to the result. There is NO empty identity — a zero-size
/// input raises, like <see cref="Max(NDExpr)"/>.
/// </summary>
public static NDExpr Ptp(NDExpr x) => new ReduceNode(NDExprReduceKind.Ptp, x);
/// <summary>
/// One-pass fused <c>np.nanmin</c>: the minimum of the expression with NaNs ignored. On a
/// float/complex child NaNs are skipped (an ALL-NaN input yields NaN); on an integer/bool child —
/// which carries no NaN — it is exactly the plain minimum, preserving the child dtype. A zero-size
/// input raises (no identity), like <see cref="Min(NDExpr)"/>.
/// </summary>
public static NDExpr NanMin(NDExpr x) => new ReduceNode(NDExprReduceKind.NanMin, x);
/// <summary>
/// One-pass fused <c>np.nanmax</c>: the maximum of the expression with NaNs ignored — the
/// <see cref="NanMin(NDExpr)"/> twin.
/// </summary>
public static NDExpr NanMax(NDExpr x) => new ReduceNode(NDExprReduceKind.NanMax, x);
// --- index reductions (plan P2 M4c) -------------------------------------------------------
//
// ArgMax/ArgMin are the M4c kinds that land NOW (unlike NanMean/Std/Var/weighted Average, which
// are summation-bound and wait on M3's streaming pairwise): they are ORDER-DETERMINISTIC over a
// C-order buffer rather than value-order-independent, so they ride the SAME host-delegation the
// M4-tail min/max kinds do — materialize the child once, then reduce it through the engine's
// already-NumPy-exact np.argmax / np.argmin. Two things set them apart from the value kinds:
// the result dtype is int64 (an INDEX, not a child-typed value), and the answer depends on the
// C-order tie/NaN rule (first maximum / first NaN wins) — which is bit-exact only because the
// materialized child is the fresh C-contiguous buffer NumPy's own argmax would build. Because
// that index is deterministic, they carry NO MisalignedRegistry excuse.
/// <summary>
/// One-pass fused <c>np.argmax</c>: the <b>int64</b> index of the maximum element of the
/// expression (flattened). Ties break to the FIRST occurrence and a NaN is treated as the
/// largest value (so the first NaN's index wins), matching NumPy over the C-order materialized
/// child. A zero-size input raises (no identity), like <see cref="Max(NDExpr)"/>.
/// </summary>
public static NDExpr ArgMax(NDExpr x) => new ReduceNode(NDExprReduceKind.ArgMax, x);
/// <summary>
/// One-pass fused <c>np.argmin</c>: the <b>int64</b> index of the minimum element of the
/// expression (flattened) — the <see cref="ArgMax(NDExpr)"/> twin (first-tie / first-NaN wins).
/// </summary>
public static NDExpr ArgMin(NDExpr x) => new ReduceNode(NDExprReduceKind.ArgMin, x);
// --- axis-aware forms of the M4 reductions (one pass along `axis`) ------------------------
/// <summary>One-pass fused <c>np.any</c> along <paramref name="axis"/> (bool result; identity <c>False</c>).</summary>
public static NDExpr Any(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Any, ComparisonNode.TruthTest(x), axis, keepdims);
/// <summary>One-pass fused <c>np.all</c> along <paramref name="axis"/> (bool result; identity <c>True</c>).</summary>
public static NDExpr All(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.All, ComparisonNode.TruthTest(x), axis, keepdims);
/// <summary>One-pass fused <c>np.count_nonzero</c> along <paramref name="axis"/> (int64 count).</summary>
public static NDExpr CountNonzero(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Sum, ComparisonNode.TruthTest(x), axis, keepdims);
/// <summary>One-pass fused <c>np.nansum</c> along <paramref name="axis"/> (NaNs treated as 0).</summary>
public static NDExpr NanSum(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Sum, Where(IsNaN(x), Const(0), x), axis, keepdims, 0, nanFamily: true);
/// <summary>One-pass fused <c>np.nanprod</c> along <paramref name="axis"/> (NaNs treated as 1).</summary>
public static NDExpr NanProd(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Prod, Where(IsNaN(x), Const(1), x), axis, keepdims, 0, nanFamily: true);
/// <summary>One-pass fused <c>np.ptp</c> along <paramref name="axis"/> (max − min; dtype preserved, wrapping).</summary>
public static NDExpr Ptp(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.Ptp, x, axis, keepdims);
/// <summary>One-pass fused <c>np.nanmin</c> along <paramref name="axis"/> (NaNs ignored; all-NaN slice → NaN).</summary>
public static NDExpr NanMin(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.NanMin, x, axis, keepdims);
/// <summary>One-pass fused <c>np.nanmax</c> along <paramref name="axis"/> (NaNs ignored; all-NaN slice → NaN).</summary>
public static NDExpr NanMax(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.NanMax, x, axis, keepdims);
/// <summary>One-pass fused <c>np.argmax</c> along <paramref name="axis"/> (int64 indices; first-tie / first-NaN wins).</summary>
public static NDExpr ArgMax(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.ArgMax, x, axis, keepdims);
/// <summary>One-pass fused <c>np.argmin</c> along <paramref name="axis"/> (int64 indices; first-tie / first-NaN wins).</summary>
public static NDExpr ArgMin(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.ArgMin, x, axis, keepdims);
// --- mean / variance / std reductions (plan P2 M4c summation kinds) -----------------------
//
// These are the summation-bound M4c kinds. Unlike the M4-tail min/max (order-INDEPENDENT) they
// are two-pass and drift through the engine's own np.var/np.nanmean (whose flat sum is a
// multi-accumulator SIMD fold, not NumPy's pairwise), so they can NOT be delegated to those.
// Instead the host materializes the child once and reproduces NumPy's _var / nanmean op for op
// over the SAME NumPy-exact pairwise sum the M1/M2 diverts use — bit-exact by construction,
// needing no fold kernel (EmitFold is untouched) and carrying NO MisalignedRegistry excuse.
// (Weighted np.average is NOT here: it reduces over TWO operands — values and weights — which the
// single-child ReduceNode cannot carry; it awaits a two-operand reduce node.)
/// <summary>
/// One-pass fused <c>np.nanmean</c>: the arithmetic mean with NaNs skipped. Result dtype follows
/// <see cref="Mean(NDExpr)"/> (int/bool→float64, float16→float16, float32/float64 preserved,
/// complex128 preserved); an ALL-NaN input yields NaN, and an integer/bool child (no NaN) is
/// exactly <see cref="Mean(NDExpr)"/>.
/// </summary>
public static NDExpr NanMean(NDExpr x) => new ReduceNode(NDExprReduceKind.NanMean, x);
/// <summary>One-pass fused <c>np.nanmean</c> along <paramref name="axis"/> (NaNs skipped per slab).</summary>
public static NDExpr NanMean(NDExpr x, int axis, bool keepdims = false) => new ReduceNode(NDExprReduceKind.NanMean, x, axis, keepdims);
/// <summary>
/// One-pass fused <c>np.var</c>: the variance with <paramref name="ddof"/> delta degrees of
/// freedom (<c>Σ(x−mean)² / (N−ddof)</c>; <c>ddof=0</c> is the population variance). Result dtype:
/// int/bool→float64, float16→float16, float32/float64 preserved, and a complex128 child yields a
/// <b>real</b> float64 variance. A NaN PROPAGATES; <c>ddof ≥ N</c> → <c>+inf</c>; empty → NaN.
/// </summary>
/// <param name="x">The expression to reduce.</param>
/// <param name="ddof">Delta degrees of freedom; the divisor is <c>max(N − ddof, 0)</c>.</param>
public static NDExpr Var(NDExpr x, int ddof = 0) => new ReduceNode(NDExprReduceKind.Var, x, ddof: ddof);
/// <summary>One-pass fused <c>np.var</c> along <paramref name="axis"/> with <paramref name="ddof"/> delta degrees of freedom.</summary>
public static NDExpr Var(NDExpr x, int axis, bool keepdims = false, int ddof = 0) => new ReduceNode(NDExprReduceKind.Var, x, axis, keepdims, ddof);
/// <summary>
/// One-pass fused <c>np.std</c>: the standard deviation <c>sqrt(var)</c> with <paramref name="ddof"/>
/// delta degrees of freedom (the <see cref="Var(NDExpr,int)"/> twin — same dtypes, NaN-propagation
/// and empty→NaN semantics, a real float64 for a complex128 child).
/// </summary>
/// <param name="x">The expression to reduce.</param>
/// <param name="ddof">Delta degrees of freedom; the divisor is <c>max(N − ddof, 0)</c>.</param>
public static NDExpr Std(NDExpr x, int ddof = 0) => new ReduceNode(NDExprReduceKind.Std, x, ddof: ddof);
/// <summary>One-pass fused <c>np.std</c> along <paramref name="axis"/> with <paramref name="ddof"/> delta degrees of freedom.</summary>
public static NDExpr Std(NDExpr x, int axis, bool keepdims = false, int ddof = 0) => new ReduceNode(NDExprReduceKind.Std, x, axis, keepdims, ddof);
// --- weighted average (plan P2 M4c-average) -----------------------------------------------
//
// np.average(values, weights) = Σ(values·weights) / Σ(weights) — the FIRST reduction that
// reduces over TWO operand trees, which the single-child ReduceNode cannot carry. It is its
// own node (WeightedAverageNode) rather than a factory rewrite because both sums must run at
// ONE result dtype that neither child's natural dtype equals (NumPy forces the product AND both
// sums to `result_dtype`, e.g. int·int → a float64 product, never the wrapping int64 one), and
// because the division of two reductions is not itself an elementwise node. The numerics are
// already available: both sums are the M1/M2-exact pairwise, so this is a node-shape change, not
// a new kernel — the host materializes both children once and reproduces NumPy's own average op
// for op (see DefaultEngine.EvaluateWeightedAverage), BIT-EXACT for the Single/Double/Complex
// result dtypes with NO MisalignedRegistry excuse; Half/Decimal are rejected (the "no float16
// pairwise kernel" gap M1/M2/M4c-summation share).
/// <summary>
/// One-pass fused <c>np.average</c>: the weighted mean <c>Σ(values·weights) / Σ(weights)</c> of
/// two expression trees (flattened). The two trees BROADCAST together like any fused binary, and
/// the result matches <c>np.average(V, weights=W)</c> on same-shape operands. The result dtype is
/// <b>float/complex</b> (NumPy's rule, keyed on the VALUES dtype: an integer/bool values tree
/// promotes to <c>result_type(values, weights, float64)</c>, else <c>result_type(values,
/// weights)</c>) — so an integer average is always at least float64, and the product/sums run at
/// that dtype (no integer wrap). A NaN in either tree PROPAGATES to NaN. Weights that sum to zero
/// (an empty input included) raise <see cref="DivideByZeroException"/> "Weights sum to zero, can't
/// be normalized", exactly as <see cref="np.average(NDArray, NDAxis?, NDArray, bool, bool)"/> does. A
/// float16 or decimal result dtype is rejected with a directed <see cref="NotSupportedException"/>
/// (a bit-exact reduction there needs a pairwise sum kernel that dtype lacks).
/// </summary>
/// <param name="values">The value expression to average.</param>
/// <param name="weights">The weight expression; each value is weighted by the aligned weight, and the sum is normalized by the total weight.</param>
/// <returns>The fused weighted-average node (root-only, like every reduction).</returns>
public static NDExpr Average(NDExpr values, NDExpr weights) => new WeightedAverageNode(values, weights);
/// <summary>
/// One-pass fused <c>np.average</c> along <paramref name="axis"/>: <c>Σ(values·weights) /
/// Σ(weights)</c> reduced over a single axis (the <see cref="Average(NDExpr,NDExpr)"/> twin — same
/// result dtype, NaN propagation, and zero-weight <see cref="DivideByZeroException"/>). Both sums
/// reduce along <paramref name="axis"/>; <paramref name="keepdims"/> re-inserts it as size 1.
/// </summary>
/// <param name="values">The value expression to average.</param>
/// <param name="weights">The weight expression aligned with <paramref name="values"/>.</param>
/// <param name="axis">The axis to reduce (negative counts from the end).</param>
/// <param name="keepdims">When true, the reduced axis is kept as a size-1 dimension.</param>
/// <returns>The fused weighted-average node reducing along <paramref name="axis"/>.</returns>
public static NDExpr Average(NDExpr values, NDExpr weights, int axis, bool keepdims = false)
=> new WeightedAverageNode(values, weights, axis, keepdims);
// --- axis=None + keepdims flat forms (plan P2 M5) -----------------------------------------
//
// NumPy's reductions take keepdims with axis=None too: np.sum(a, keepdims=True) reduces the
// whole array yet returns shape (1,)*a.ndim — the broadcast-friendly form behind idioms like
// `a / a.sum(axis=None, keepdims=True)`. The flat factories above return a 0-d scalar
// (keepdims=False); these are their keepdims twins. The bool is REQUIRED (no default) on
// purpose: `Sum(x)` must stay unambiguously the 0-d form, so `Sum(x, keepdims: true)` — a
// required argument — is the only way into the size-1-everywhere form (a defaulted overload
// would collide with `Sum(x)`). The host reshapes the 0-d result to (1,)*childNdim, so the
// VALUE is identical to the 0-d form and only the wrapper rank differs; a 0-d child stays 0-d
// (np.sum(scalar, keepdims=True) is 0-d), matching NumPy. TUPLE axis is deliberately NOT
// offered — every NumSharp reduction is single-axis (int?), so multi-axis is a library-wide
// gap, not an evaluate-specific one (plan P2 M5, deferred).
/// <summary>One-pass fused <c>np.sum(x, axis=None, keepdims=True)</c> — the whole-array sum kept as shape (1,…,1) for broadcasting back against the input.</summary>
public static NDExpr Sum(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Sum, x, null, keepdims);
/// <summary>One-pass fused <c>np.prod(x, axis=None, keepdims=True)</c> — the whole-array product kept as shape (1,…,1).</summary>
public static NDExpr Prod(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Prod, x, null, keepdims);
/// <summary>One-pass fused <c>np.min(x, axis=None, keepdims=True)</c> — the whole-array minimum kept as shape (1,…,1) (NaN-propagating).</summary>
public static NDExpr Min(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Min, x, null, keepdims);
/// <summary>One-pass fused <c>np.max(x, axis=None, keepdims=True)</c> — the whole-array maximum kept as shape (1,…,1) (NaN-propagating).</summary>
public static NDExpr Max(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Max, x, null, keepdims);
/// <summary>One-pass fused <c>np.mean(x, axis=None, keepdims=True)</c> — the whole-array mean kept as shape (1,…,1).</summary>
public static NDExpr Mean(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Mean, x, null, keepdims);
/// <summary>One-pass fused <c>np.any(x, axis=None, keepdims=True)</c> — the whole-array presence test kept as shape (1,…,1) (bool).</summary>
public static NDExpr Any(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Any, ComparisonNode.TruthTest(x), null, keepdims);
/// <summary>One-pass fused <c>np.all(x, axis=None, keepdims=True)</c> — the whole-array universal test kept as shape (1,…,1) (bool).</summary>
public static NDExpr All(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.All, ComparisonNode.TruthTest(x), null, keepdims);
/// <summary>One-pass fused <c>np.count_nonzero(x, axis=None, keepdims=True)</c> — the whole-array nonzero count kept as shape (1,…,1) (int64).</summary>
public static NDExpr CountNonzero(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Sum, ComparisonNode.TruthTest(x), null, keepdims);
/// <summary>One-pass fused <c>np.nansum(x, axis=None, keepdims=True)</c> — the whole-array NaN-skipping sum kept as shape (1,…,1).</summary>
public static NDExpr NanSum(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Sum, Where(IsNaN(x), Const(0), x), null, keepdims, 0, nanFamily: true);
/// <summary>One-pass fused <c>np.nanprod(x, axis=None, keepdims=True)</c> — the whole-array NaN-skipping product kept as shape (1,…,1).</summary>
public static NDExpr NanProd(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Prod, Where(IsNaN(x), Const(1), x), null, keepdims, 0, nanFamily: true);
/// <summary>One-pass fused <c>np.ptp(x, axis=None, keepdims=True)</c> — the whole-array peak-to-peak range kept as shape (1,…,1) (dtype preserved, wrapping).</summary>
public static NDExpr Ptp(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.Ptp, x, null, keepdims);
/// <summary>One-pass fused <c>np.nanmin(x, axis=None, keepdims=True)</c> — the whole-array NaN-skipping minimum kept as shape (1,…,1).</summary>
public static NDExpr NanMin(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.NanMin, x, null, keepdims);
/// <summary>One-pass fused <c>np.nanmax(x, axis=None, keepdims=True)</c> — the whole-array NaN-skipping maximum kept as shape (1,…,1).</summary>
public static NDExpr NanMax(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.NanMax, x, null, keepdims);
/// <summary>One-pass fused <c>np.argmax(x, axis=None, keepdims=True)</c> — the flat int64 index of the maximum kept as shape (1,…,1) (first-tie / first-NaN wins).</summary>
public static NDExpr ArgMax(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.ArgMax, x, null, keepdims);
/// <summary>One-pass fused <c>np.argmin(x, axis=None, keepdims=True)</c> — the flat int64 index of the minimum kept as shape (1,…,1) (first-tie / first-NaN wins).</summary>
public static NDExpr ArgMin(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.ArgMin, x, null, keepdims);
/// <summary>One-pass fused <c>np.nanmean(x, axis=None, keepdims=True)</c> — the whole-array NaN-skipping mean kept as shape (1,…,1).</summary>
public static NDExpr NanMean(NDExpr x, bool keepdims) => new ReduceNode(NDExprReduceKind.NanMean, x, null, keepdims);
/// <summary>One-pass fused <c>np.var(x, axis=None, keepdims=True, ddof=ddof)</c> — the whole-array variance kept as shape (1,…,1) (real float64 for a complex child).</summary>
/// <param name="x">The expression to reduce.</param>
/// <param name="keepdims">Kept for API shape; a flat variance kept as size-1 everywhere.</param>
/// <param name="ddof">Delta degrees of freedom; the divisor is <c>max(N − ddof, 0)</c>.</param>
public static NDExpr Var(NDExpr x, bool keepdims, int ddof = 0) => new ReduceNode(NDExprReduceKind.Var, x, null, keepdims, ddof);
/// <summary>One-pass fused <c>np.std(x, axis=None, keepdims=True, ddof=ddof)</c> — the whole-array standard deviation kept as shape (1,…,1).</summary>
/// <param name="x">The expression to reduce.</param>
/// <param name="keepdims">Kept for API shape; a flat std kept as size-1 everywhere.</param>
/// <param name="ddof">Delta degrees of freedom; the divisor is <c>max(N − ddof, 0)</c>.</param>
public static NDExpr Std(NDExpr x, bool keepdims, int ddof = 0) => new ReduceNode(NDExprReduceKind.Std, x, null, keepdims, ddof);
/// <summary>One-pass fused <c>np.average(values, weights=weights, axis=None, keepdims=True)</c> — the whole-array weighted mean kept as shape (1,…,1).</summary>
/// <param name="values">The value expression to average.</param>
/// <param name="weights">The weight expression aligned with <paramref name="values"/>.</param>
/// <param name="keepdims">Kept for API shape; a flat weighted average kept as size-1 everywhere.</param>
/// <returns>The fused weighted-average node reducing the whole array, result kept as shape (1,…,1).</returns>
public static NDExpr Average(NDExpr values, NDExpr weights, bool keepdims)
=> new WeightedAverageNode(values, weights, null, keepdims);
// ===================================================================
// Binding
// ===================================================================
/// <summary>
/// Rewrite array leaves into positional inputs, collecting the distinct
/// arrays into <paramref name="ctx"/>. Returns the same instance when
/// the subtree contains no array leaf.
/// </summary>
internal abstract NDExpr BindArrays(NDExprBindContext ctx);
/// <summary>True if any node in the subtree is a <see cref="ReduceNode"/>.</summary>
internal abstract bool ContainsReduce { get; }
/// <summary>
/// The first embedded <see cref="NDArray"/> leaf in evaluation order, or null for a tree
/// built over positional inputs / constants. np.evaluate dispatches on its engine.
/// </summary>
internal virtual NDArray FirstArray() => null;
}
public sealed partial class InputNode
{
/// <summary>
/// A positional leaf is already bound, so binding keeps it — unless a pass over a bound tree supplied
/// <see cref="NDExprBindContext.InputRewrite"/>, which may renumber it (the fmax / fmin staging evaluates a child
/// subtree over just the operands it reads).
/// </summary>
/// <param name="ctx">The binding pass.</param>
/// <returns>This leaf, or the rewrite's replacement.</returns>
internal override NDExpr BindArrays(NDExprBindContext ctx) => ctx.InputRewrite?.Invoke(this) ?? this;
internal override bool ContainsReduce => false;
}
public sealed partial class ConstNode
{
internal override NDExpr BindArrays(NDExprBindContext ctx) => this;
internal override bool ContainsReduce => false;
}
public sealed partial class BinaryNode
{
/// <summary>
/// Binds both children, then rebuilds this node over them (this node itself when neither changed). A pass over a
/// bound tree may replace the whole node through <see cref="NDExprBindContext.BinaryRewrite"/>, which sees the
/// children already rewritten — the fmax / fmin staging turns a float fmax / fmin into a stage-result leaf there.
/// </summary>
/// <param name="ctx">The binding pass.</param>
/// <returns>The bound node: this node, a rebuilt one, or the rewrite's replacement.</returns>
internal override NDExpr BindArrays(NDExprBindContext ctx)
{
var l = _left.BindArrays(ctx);
var r = _right.BindArrays(ctx);
// A staging pass may replace this node once its children are rewritten (null in ordinary binding).
if (ctx.BinaryRewrite?.Invoke(this, l, r) is { } replaced)
return replaced;
return ReferenceEquals(l, _left) && ReferenceEquals(r, _right)
? this
: new BinaryNode(_op, l, r);
}
internal override bool ContainsReduce => _left.ContainsReduce || _right.ContainsReduce;
internal override NDArray FirstArray() => _left.FirstArray() ?? _right.FirstArray();
}
public sealed partial class UnaryNode
{
internal override NDExpr BindArrays(NDExprBindContext ctx)
{
var c = _child.BindArrays(ctx);
return ReferenceEquals(c, _child) ? this : new UnaryNode(_op, c);
}
internal override bool ContainsReduce => _child.ContainsReduce;
internal override NDArray FirstArray() => _child.FirstArray();
}
public sealed partial class CastNode
{
/// <summary>
/// Binds the child, rebuilding this node over it (this node itself when it did not change); the rebuilt node keeps
/// a text target's descriptor. A cast TO text has no kernel — only the text plan runs it, as NumPy's
/// <c>astype</c> stage — so binding one marks the tree as holding a stage-only node, which sends a tree over numbers
/// alone (<c>Cast(age, "U5")</c>) to the text plan too.
/// </summary>
/// <param name="ctx">The binding pass.</param>
/// <returns>This node, or a copy over the bound child.</returns>
internal override NDExpr BindArrays(NDExprBindContext ctx)
{
if (_textTarget is not null)
ctx.HoldsStageOnlyNode = true;
var c = _child.BindArrays(ctx);
if (ReferenceEquals(c, _child))
return this;
return _textTarget is not null ? new CastNode(c, _textTarget) : new CastNode(c, _target);
}
internal override bool ContainsReduce => _child.ContainsReduce;
internal override NDArray FirstArray() => _child.FirstArray();
}
public sealed partial class RoundNode
{
internal override NDExpr BindArrays(NDExprBindContext ctx)
{
var c = _child.BindArrays(ctx);
return ReferenceEquals(c, _child) ? this : new RoundNode(c, _decimals);
}
internal override bool ContainsReduce => _child.ContainsReduce;
internal override NDArray FirstArray() => _child.FirstArray();
}
public sealed partial class ComparisonNode
{
internal override NDExpr BindArrays(NDExprBindContext ctx)
{
var l = _left.BindArrays(ctx);
var r = _right.BindArrays(ctx);
// The rebuilt node keeps the truth-test flag (dropping it would let a factory's Any / All / CountNonzero of
// text lower as a plain comparison).
return ReferenceEquals(l, _left) && ReferenceEquals(r, _right)
? this
: new ComparisonNode(_op, l, r, _truthTest);
}
internal override bool ContainsReduce => _left.ContainsReduce || _right.ContainsReduce;
internal override NDArray FirstArray() => _left.FirstArray() ?? _right.FirstArray();
}
public sealed partial class MinMaxNode
{
/// <summary>
/// Binds the array leaves below this node, rebuilding the node only when a child changed; the rebuilt node keeps
/// the min/max kind and the clip-half flag (dropping the flag would turn a complex clip into np.maximum's selection).
/// </summary>
/// <param name="ctx">The binding context that deduplicates array operands.</param>
/// <returns>This node, or a copy over the bound children.</returns>
internal override NDExpr BindArrays(NDExprBindContext ctx)
{
var l = _left.BindArrays(ctx);
var r = _right.BindArrays(ctx);
return ReferenceEquals(l, _left) && ReferenceEquals(r, _right)
? this
: new MinMaxNode(_isMin, l, r, _clipSelection);
}
internal override bool ContainsReduce => _left.ContainsReduce || _right.ContainsReduce;
internal override NDArray FirstArray() => _left.FirstArray() ?? _right.FirstArray();
}
public sealed partial class WhereNode
{
internal override NDExpr BindArrays(NDExprBindContext ctx)
{
var c = _cond.BindArrays(ctx);
var a = _a.BindArrays(ctx);
var b = _b.BindArrays(ctx);
return ReferenceEquals(c, _cond) && ReferenceEquals(a, _a) && ReferenceEquals(b, _b)
? this
: new WhereNode(c, a, b);
}
internal override bool ContainsReduce => _cond.ContainsReduce || _a.ContainsReduce || _b.ContainsReduce;
internal override NDArray FirstArray() => _cond.FirstArray() ?? _a.FirstArray() ?? _b.FirstArray();
}
public sealed partial class LogicalNode
{
internal override NDExpr BindArrays(NDExprBindContext ctx)
{
var l = _left.BindArrays(ctx);
var r = _right.BindArrays(ctx);
return ReferenceEquals(l, _left) && ReferenceEquals(r, _right)
? this
: new LogicalNode(_op, l, r);
}
internal override bool ContainsReduce => _left.ContainsReduce || _right.ContainsReduce;
internal override NDArray FirstArray() => _left.FirstArray() ?? _right.FirstArray();
}
public sealed partial class CallNode
{
/// <summary>Clone with new args — reuses the registered slot/method, no re-registration.</summary>
private CallNode(CallNode source, NDExpr[] args)
{
_kind = source._kind;
_method = source._method;
_delegateType = source._delegateType;
_slotId = source._slotId;
_args = args;
_paramCodes = source._paramCodes;
_returnCode = source._returnCode;
_signatureId = source._signatureId;
}
internal override NDExpr BindArrays(NDExprBindContext ctx)
{
NDExpr[]? rebound = null;
for (int i = 0; i < _args.Length; i++)
{
var b = _args[i].BindArrays(ctx);
if (!ReferenceEquals(b, _args[i]) && rebound is null)
{
rebound = new NDExpr[_args.Length];
Array.Copy(_args, rebound, i);
}
if (rebound is not null)
rebound[i] = b;
}
return rebound is null ? this : new CallNode(this, rebound);
}
internal override bool ContainsReduce
{
get
{
foreach (var a in _args)
if (a.ContainsReduce)
return true;
return false;
}
}
internal override NDArray FirstArray()
{
foreach (var a in _args)
{
var arr = a.FirstArray();
if (arr is not null)
return arr;
}
return null;
}
}
// =========================================================================
// Node: ArrayNode — an NDArray leaf, replaced by Input(i) during binding.
// Never reaches typing or emission: np.evaluate always binds first.
// =========================================================================
[NDBorrowed] // an expression leaf references the caller's array; np.evaluate never owns its inputs
public sealed partial class ArrayNode : NDExpr
{
private readonly NDArray _array;
public ArrayNode(NDArray array)
=> _array = array ?? throw new ArgumentNullException(nameof(array));
internal NDArray Array => _array;
public override bool SupportsSimd => true;
public override void EmitScalar(ILGenerator il, NDExprCompileContext ctx)
=> throw new InvalidOperationException(
"ArrayNode must be bound before compilation — evaluate the tree via np.evaluate, " +
"or rewrite array leaves to NDExpr.Input(i) and pass the arrays to the iterator.");
public override void EmitVector(ILGenerator il, NDExprCompileContext ctx)
=> throw new InvalidOperationException(
"ArrayNode must be bound before compilation — evaluate the tree via np.evaluate.");
public override void AppendSignature(StringBuilder sb)
=> sb.Append("Arr[unbound]");
internal override NDExprTypeInfo InferType(
NPTypeCode[] inputTypes, Dictionary<NDExpr, NPTypeCode> nodeTypes)
=> throw new InvalidOperationException(
"ArrayNode must be bound before typing — evaluate the tree via np.evaluate.");
internal override NDExpr BindArrays(NDExprBindContext ctx)
=> new InputNode(ctx.IndexOf(_array));
internal override bool ContainsReduce => false;
internal override NDArray FirstArray() => _array;
}
// =========================================================================
// Node: ReduceNode — root-only fused reduction over an elementwise tree.
//
// np.evaluate drives it as: iterate the INPUT operands only (no output
// operand), run a raw accumulating inner loop that evaluates the child
// tree per element and folds into a host-owned accumulator slot (aux).
//
// dtype rules (NumPy 2.4.2, probed):
// sum/prod: bool/int→int64, uint→uint64, floats preserved
// min/max: input dtype preserved
// mean: bool/int→float64, floats preserved
//
// Accumulation detail: float sums/products/means accumulate in float64
// and cast back once at the end — tighter than NumPy's pairwise f32 loop,
// so f32 results can differ from np.sum in the last ulps (documented).
// Min/max accumulate at the exact result dtype (comparisons are exact)
// and propagate NaN like np.min/np.max.
// =========================================================================