The upper incomplete gamma function

BREAKING-CHANGES.md

@@ -129,6 +129,23 @@ as `a - b = 0`, as a statement's own solve reads it: `"x + 1 = 3".Solve("x")` wa
 | `"polygamma(1, 3)".ToEntity().InnerSimplified` | an `UnhandledParseException` | `1/6 * pi ^ 2 - 5/4` |
 | `"digamma(x)".ToEntity().Integrate("x")` | `digamma * x ^ 2 / 2 + C`, of the product | `ln((x - 1)!) + C` |
 
+### `gamma(a, z)` is the upper incomplete gamma function
+
+**Not silent: what was a parse error is a function.** `gamma` took one argument, and a second was a
+`FunctionArgumentCountException`. With two it is now the upper incomplete gamma function,
+`Gamma(a, z) = int_z^oo t^(a - 1) e^(-t) dt`, as Mathematica's `Gamma[a, z]` is.
+- **Branch.** It takes the principal branch of `z^a`, with the cut on the negative real axis.
+- **Evaluation.** It is evaluated to the working precision for any complex `a` and `z`.
+- **Derivative.** In `z` it is `-z^(a - 1) e^(-z)`.
+- **Exact forms.** A whole `a >= 1` and `a = 1/2` are elementary.
+([#2075](https://github.com/asc-community/AngouriMath/issues/2075))
+
+| Input | Was (2.6.0) | Now |
+|---|---|---|
+| `"gamma(1/3, x)".ToEntity()` | a `FunctionArgumentCountException` | `gamma(1/3, x)` |
+| `"gamma(1/3, 2)".EvalNumerical()` | a `FunctionArgumentCountException` | `0.068136414441459136…` |
+| `"gamma(3, x)".ToEntity().InnerSimplified` | a `FunctionArgumentCountException` | `2 * e ^ (-x) * (1 + x + x ^ 2 / 2)` |
+
 ### Numerical equality is to half the evaluation's digits
 
 **Silent: wrong answers.** `MathS.UnsafeAndInternal.AreEqualNumerically` evaluated both sides at its check points and

Sources/.editorconfig

@@ -699,6 +699,12 @@ file_header_template=\nCopyright (c) 2019-2026 Angouri.\nAngouriMath is licensed
 [AngouriMath/Core/Entity/Continuous/Number/Polygamma.cs]
 file_header_template=\nCopyright (c) 2019-2026 Angouri.\nAngouriMath is licensed under MIT.\nDetails: https://github.com/asc-community/AngouriMath/blob/master/LICENSE.md.\nWebsite: https://am.angouri.org.\n
 
+[AngouriMath/Core/Entity/Continuous/Number/IncompleteGamma.cs]
+file_header_template=\nCopyright (c) 2019-2026 Angouri.\nAngouriMath is licensed under MIT.\nDetails: https://github.com/asc-community/AngouriMath/blob/master/LICENSE.md.\nWebsite: https://am.angouri.org.\n
+
+[AngouriMath/Core/Entity/Continuous/Entity.Continuous.IncompleteGamma.Classes.cs]
+file_header_template=\nCopyright (c) 2019-2026 Angouri.\nAngouriMath is licensed under MIT.\nDetails: https://github.com/asc-community/AngouriMath/blob/master/LICENSE.md.\nWebsite: https://am.angouri.org.\n
+
 [AngouriMath/Core/Entity/Continuous/Entity.Continuous.Polygamma.Classes.cs]
 file_header_template=\nCopyright (c) 2019-2026 Angouri.\nAngouriMath is licensed under MIT.\nDetails: https://github.com/asc-community/AngouriMath/blob/master/LICENSE.md.\nWebsite: https://am.angouri.org.\n
 

Sources/AngouriMath/Convenience/MathS.cs

@@ -1474,6 +1474,19 @@ public static Entity VectorLength(Matrix v)
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static Entity Digamma(Entity argument) => new Polygammaf(Integer.Zero, argument);
 
+        /// <summary>The upper incomplete gamma function, <c>Gamma(a, z) = int_z^oo t^(a - 1) e^(-t) dt</c></summary>
+        /// <param name="parameter">The parameter <c>a</c>, any complex number</param>
+        /// <param name="lowerLimit">The lower limit <c>z</c>, any complex number; <c>0</c> only where <c>Re a > 0</c></param>
+        /// <returns>The <see cref="Entity.IncompleteGammaf"/> node</returns>
+        /// <remarks>
+        /// <c>z^a</c> takes its principal branch, so the cut is the negative real axis, which keeps the value from above.
+        /// <c>Gamma(a, 0)</c> is <c>Gamma(a)</c>, and the derivative in <c>z</c> is <c>-z^(a - 1) e^(-z)</c>. It is written
+        /// <c>gamma(a, z)</c>, as Mathematica's <c>Gamma[a, z]</c> and mpmath's <c>gammainc(a, z)</c> are.
+        /// https://github.com/asc-community/AngouriMath/issues/2075
+        /// </remarks>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static Entity IncompleteGamma(Entity parameter, Entity lowerLimit) => new IncompleteGammaf(parameter, lowerLimit);
+
         /// <summary>The sine integral, <c>Si(z) = int_0^z sin(t)/t dt</c></summary>
         /// <param name="a">The argument, any complex number</param>
         /// <returns>The <see cref="Entity.Sif"/> node</returns>

Sources/AngouriMath/Core/Antlr/AngouriMath.g

@@ -543,7 +543,9 @@ atom returns[Entity value]
 
 
     | 'factorial(' args = function_arguments ')' { Assert("factorial", 1, $args.list.Count); $value = MathS.Factorial($args.list[0]); }
-    | 'gamma(' args = function_arguments ')' { Assert("gamma", 1, $args.list.Count); $value = MathS.Gamma($args.list[0]); }
+    /* With a second argument, the upper incomplete gamma function Gamma(a, z), as Mathematica's Gamma[a, z].
+       https://github.com/asc-community/AngouriMath/issues/2075 */
+    | 'gamma(' args = function_arguments ')' { if ($args.list.Count == 2) $value = MathS.IncompleteGamma($args.list[0], $args.list[1]); else { Assert("gamma", 1, $args.list.Count); $value = MathS.Gamma($args.list[0]); } }
     | 'derivative(' args = function_arguments ')' 
         {
             if (Assert("derivative", (3, 2), $args.list.Count))

Sources/AngouriMath/Core/Antlr/AngouriMathParser.cs

@@ -4369,7 +4369,7 @@ public AtomContext atom() {
 				_localctx.args = function_arguments();
 				State = 886;
 				Match(T__30);
-				 Assert("gamma", 1, _localctx.args.list.Count); _localctx.value =  MathS.Gamma(_localctx.args.list[0]); 
+				 if (_localctx.args.list.Count == 2) _localctx.value =  MathS.IncompleteGamma(_localctx.args.list[0], _localctx.args.list[1]); else { Assert("gamma", 1, _localctx.args.list.Count); _localctx.value =  MathS.Gamma(_localctx.args.list[0]); } 
 				}
 				break;
 			case 94:

Sources/AngouriMath/Core/Domains.Classes.cs

@@ -384,6 +384,14 @@ partial record Polygammaf
             internal override Domain DefaultCodomain => Domain.Complex;
         }
 
+        partial record IncompleteGammaf
+        {
+            /// <inheritdoc/>
+            public override Domain Codomain { get; protected init; } = Domain.Complex;
+            /// <inheritdoc/>
+            internal override Domain DefaultCodomain => Domain.Complex;
+        }
+
         partial record Sif
         {
             /// <inheritdoc/>

Sources/AngouriMath/Core/Entity/Continuous/Entity.Continuous.IncompleteGamma.Classes.cs

@@ -0,0 +1,36 @@
+//
+// Copyright (c) 2019-2026 Angouri.
+// AngouriMath is licensed under MIT.
+// Details: https://github.com/asc-community/AngouriMath/blob/master/LICENSE.md.
+// Website: https://am.angouri.org.
+//
+
+using System;
+
+namespace AngouriMath
+{
+    partial record Entity
+    {
+        /// <summary>
+        /// The upper incomplete gamma function, <c>Gamma(a, z) = int_z^oo t^(a - 1) e^(-t) dt</c>, with the principal branch
+        /// of <c>z^a</c>: the cut is the negative real axis.
+        /// </summary>
+        /// <remarks>https://github.com/asc-community/AngouriMath/issues/2075</remarks>
+        public sealed partial record IncompleteGammaf(Entity Parameter, Entity LowerLimit) : Function, IBinaryNode
+        {
+            private IncompleteGammaf New(Entity parameter, Entity lowerLimit) =>
+                ReferenceEquals(Parameter, parameter) && ReferenceEquals(LowerLimit, lowerLimit) ? this : new(parameter, lowerLimit) { Codomain = Codomain };
+
+            /// <inheritdoc/>
+            public Entity NodeFirstChild => Parameter;
+
+            /// <inheritdoc/>
+            public Entity NodeSecondChild => LowerLimit;
+
+            /// <inheritdoc/>
+            public override Entity Replace(Func<Entity, Entity> func) => func(New(Parameter.Replace(func), LowerLimit.Replace(func)));
+            /// <inheritdoc/>
+            protected override Entity[] InitDirectChildren() => new[] { Parameter, LowerLimit };
+        }
+    }
+}