Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -821,6 +821,7 @@ are short, and a stale one is worse than none — if you change what a file desc
| [CONTRIBUTING.md](CONTRIBUTING.md) | for humans; how to get set up and what a PR should look like |
| [`Docs/Usage/Syntax.md`](Sources/AngouriMath/Docs/Usage/Syntax.md) | what the parser accepts. The grammar was the only statement of it until [#706](https://github.com/asc-community/AngouriMath/pull/706) |
| [`Docs/Usage/Exceptions.md`](Sources/AngouriMath/Docs/Usage/Exceptions.md) | the exception hierarchy under `AngouriMathBaseException` |
| [`Docs/Usage/Shaders.md`](Sources/AngouriMath/Docs/Usage/Shaders.md) | `MathS.Shaders.Hlsl` and `Glsl`: a worked example, and where the printed shader and `Compile<double>` differ |
| [`Docs/Usage/Comparison.md`](Sources/AngouriMath/Docs/Usage/Comparison.md) | how we measure against Math.NET Symbolics, Symbolism and SymPy, with the versions and what each comparison does not establish |
| [`Docs/References.md`](Sources/AngouriMath/Docs/References.md) | the books, papers, corpora and reference works the code and its tests draw on, with the link and what each is used for. Add a work there when it is first cited |
| [`Docs/Acknowledgements.md`](Sources/AngouriMath/Docs/Acknowledgements.md) and [`Docs/Articles.md`](Sources/AngouriMath/Docs/Articles.md) | the projects AngouriMath is built with, and the maintainers' articles about it, moved from the archived AngouriMathLab |
Expand Down
17 changes: 17 additions & 0 deletions BREAKING-CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,23 @@ none of the roots takes nothing out; anything else, a symbol among them, leaves
| `"sum(x, x in { w : w^2 - 2 = 0 } \\ { sqrt(2) })".ToEntity().Simplify()` | `sum(x, x in { w : w ^ 2 - 2 = 0 } \ { sqrt(2) })` | `-sqrt(2)` |
| `"sum(x, x in { w : w^2 - 3w + 2 = 0 } \\ { 1 })".ToEntity().Simplify()` | `sum(x, x in { w : w ^ 2 - 3 * w + 2 = 0 } \ { 1 })` | `2` |

### Shader source: `MathS.Shaders.Hlsl` and `Glsl`

**Not silent: a new entry point.** `MathS.Shaders.Hlsl` and `MathS.Shaders.Glsl` print expressions as straight-line
HLSL or GLSL, one assignment per named output with each repeated subexpression computed once, and return a
`GeneratedSource` that holds the code or names the node it declined. The code computes what `Compile<double, …>`
computes, except at a zero divisor and at zero to a power that is not positive, where `Compile` answers `NaN` and the
shader ±inf (or `1.0` for an unsimplified `x^0`). The catalogue has them as `hlsl` and `glsl`. Nothing that existed
changes. See [`Docs/Usage/Shaders.md`](Sources/AngouriMath/Docs/Usage/Shaders.md)
([#2293](https://github.com/asc-community/AngouriMath/issues/2293)).

| Input | Was (2.7.0) | Now |
|---|---|---|
| `MathS.Shaders.Hlsl([new("r", "x^(-1/2) + sin(x) cos(x)")]).Code` | no such member | `float am0, am1;`<br>`sincos(x, am0, am1);`<br>`r = (rsqrt(x) + (am0 * am1));` |
| `MathS.Shaders.Hlsl([new("r", "x!")]).ToString()` | no such member | ``Declined at x!: `x!` has no intrinsic in HLSL or GLSL and no straight-line form`` |

---

### A system row that is not a solution declines the system

**Silent: a wrong row is now no answer.** With `P + Q sqrt(2) = (1 + sqrt(2))^70`, the coefficient `P - Q y` is
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -453,6 +453,10 @@ False
False
```

The same expressions can be printed as HLSL or GLSL for a shader, an exact gradient for a
signed distance field for instance: see
<a href="./Sources/AngouriMath/Docs/Usage/Shaders.md">Docs/Usage/Shaders.md</a>.

</details>

<details><summary><strong>Multithreading</strong></summary>
Expand Down
9 changes: 9 additions & 0 deletions Sources/.editorconfig
Original file line number Diff line number Diff line change
Expand Up @@ -1120,3 +1120,12 @@ file_header_template=\nCopyright (c) 2019-2026 Angouri.\nAngouriMath is licensed

[AngouriMath/Functions/Output/ToString/UnicodeSpelling.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/Functions/Compilation/IntoSource/*.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/Convenience/MathS.Shaders.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

[Tests/UnitTests/Convenience/ShadersTest.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
107 changes: 107 additions & 0 deletions Sources/AngouriMath/Convenience/MathS.Shaders.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
//
// 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 AngouriMath.Functions.Compilation.IntoSource;

namespace AngouriMath
{
using static Entity;

partial class MathS
{
/// <summary>
/// Expressions printed as shader source: straight-line HLSL or GLSL that computes each
/// output once, sharing every repeated subexpression.
/// </summary>
/// <remarks>
/// <para>
/// The use is to derive on the CPU what is expensive or error-prone to derive by hand —
/// an exact gradient, a Hessian, a closed form of a physical law — and run the result
/// on the GPU. <see cref="Entity.Differentiate(Variable)"/> followed by one of these
/// is an analytic normal for a signed distance field.
/// </para>
/// <para>
/// The code computes the real-valued reading, the one <c>Compile&lt;double, …&gt;</c>
/// computes; where that has no value the shader's is <c>NaN</c>, an infinity or
/// unspecified, as the language's own <c>/</c>, <c>pow</c> and <c>sqrt</c> leave it.
/// Three of those are worth naming, because a GPU does give them a value: a division by
/// zero, <c>a / b</c> at <c>b = 0</c>, is <c>NaN</c> compiled and ±infinity in the
/// shader; so is zero to a negative power, <c>x^(-2)</c> or <c>x^(-1/2)</c> at <c>x = 0</c>,
/// printed <c>1.0 / (x * x)</c> and <c>rsqrt(x)</c>; and an unsimplified <c>x^0</c> is
/// printed <c>1.0</c>, which is 1 at <c>x = 0</c> where compiled it is <c>NaN</c>. A
/// branch on every quotient would cost more than the difference is worth, so the
/// difference is documented rather than paid for. Nor is <c>pow</c> of a negative base
/// defined in a shader, even where the exponent is a variable that happens to be whole.
/// </para>
/// <para>
/// A node with no faithful form — a complex constant, a set, a piecewise with inputs it
/// gives no value to, a function with no intrinsic and no straight-line form — is declined
/// with the node named, never printed approximately; and what <c>Compile</c> refuses, a
/// binder or a statement where a number is expected, is declined with <c>Compile</c>'s
/// message.
/// </para>
/// <para>
/// Nothing is simplified. Call <see cref="Entity.Simplify(int)"/> first if a smaller
/// form is wanted: what is printed is the expression that was given. The only rewrites
/// are the ones <c>Compile</c> makes as well: an operation on matrices written out is
/// the number it gives, a membership in an interval or a finite set is the comparisons
/// it stands for, and <c>(b^v + c1) / (b^v + c2)</c>, as <c>tanh</c> is spelled, is taken
/// as <c>1 + (c1 - c2) / (b^v + c2)</c> so that it does not overflow.
/// </para>
/// <para>
/// The page <c>Docs/Usage/Shaders.md</c> works an example through.
/// </para>
/// </remarks>
public static class Shaders
{
/// <summary>
/// HLSL statements assigning each output: <c>float</c> locals for the shared
/// subexpressions, then one assignment per output, in the order given.
/// </summary>
/// <param name="outputs">The target of each assignment — a variable, an
/// <c>out</c> parameter, a swizzle such as <c>n.x</c> — and the expression it gets.</param>
/// <param name="names">
/// What each variable is called in the shader, such as <c>p.x</c> for <c>x</c>. A
/// variable not listed keeps its own name, which has to be an identifier.
/// </param>
/// <returns>The source, or which subexpression could not be printed faithfully and why.</returns>
/// <example>
/// <code>
/// using System;
/// using System.Collections.Generic;
/// using AngouriMath;
///
/// Entity r = "sqrt(x^2 + y^2)";
/// var source = MathS.Shaders.Hlsl(new Dictionary&lt;string, Entity&gt;
/// {
/// ["g.x"] = r.Differentiate("x"),
/// ["g.y"] = r.Differentiate("y"),
/// }.ToList(), new Dictionary&lt;Entity.Variable, string&gt; { ["x"] = "p.x", ["y"] = "p.y" });
/// Console.Write(source.Code);
/// </code>
/// Prints
/// <code>
/// float am0 = (0.5 * rsqrt(((p.x * p.x) + (p.y * p.y))));
/// g.x = (am0 * (2.0 * p.x));
/// g.y = (am0 * (2.0 * p.y));
/// </code>
/// </example>
public static GeneratedSource Hlsl(IReadOnlyList<KeyValuePair<string, Entity>> outputs, IReadOnlyDictionary<Variable, string>? names = null)
=> ShaderSource.Emit(SourceDialect.Hlsl, outputs, names);

/// <summary>
/// GLSL statements assigning each output, as <see cref="Hlsl"/> prints them, with
/// GLSL's names for the intrinsics that differ.
/// </summary>
/// <param name="outputs">The target of each assignment and the expression it gets.</param>
/// <param name="names">What each variable is called in the shader.</param>
/// <returns>The source, or which subexpression could not be printed faithfully and why.</returns>
public static GeneratedSource Glsl(IReadOnlyList<KeyValuePair<string, Entity>> outputs, IReadOnlyDictionary<Variable, string>? names = null)
=> ShaderSource.Emit(SourceDialect.Glsl, outputs, names);
}
}
}
17 changes: 16 additions & 1 deletion Sources/AngouriMath/Core/Operations/Catalogue.cs
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,21 @@ internal static class Catalogue
"sympy", "Writes the expression as Python code for SymPy.",
static e => MathS.ToSympyCode(e));

[ConstantField]
private static readonly Parameter TheShaderNames = new("names", "What each variable is called in the shader, such as p.x, or none to keep its own name.");

/// <summary><see cref="MathS.Shaders.Hlsl(IReadOnlyList{KeyValuePair{string, Entity}}, IReadOnlyDictionary{Variable, string})"/>.</summary>
public static Query<Func<IReadOnlyList<KeyValuePair<string, Entity>>, IReadOnlyDictionary<Variable, string>?, GeneratedSource>> Hlsl { get; } = new(
"hlsl", "Writes expressions as straight-line HLSL, one assignment to each named output, or names the node it has no faithful form for.",
static (outputs, names) => MathS.Shaders.Hlsl(outputs, names),
TheShaderNames);

/// <summary><see cref="MathS.Shaders.Glsl(IReadOnlyList{KeyValuePair{string, Entity}}, IReadOnlyDictionary{Variable, string})"/>.</summary>
public static Query<Func<IReadOnlyList<KeyValuePair<string, Entity>>, IReadOnlyDictionary<Variable, string>?, GeneratedSource>> Glsl { get; } = new(
"glsl", "Writes expressions as straight-line GLSL, one assignment to each named output, or names the node it has no faithful form for.",
static (outputs, names) => MathS.Shaders.Glsl(outputs, names),
TheShaderNames);

/// <summary><see cref="MathS.Boolean.BuildTruthTable(Entity, Variable[])"/>.</summary>
public static Query<Func<Entity, IReadOnlyList<Variable>, Matrix?>> TruthTable { get; } = new(
"truth_table", "Tabulates a statement over every assignment of true and false to its variables.",
Expand Down Expand Up @@ -260,7 +275,7 @@ internal static class Catalogue
public static IReadOnlyList<Operation> All { get; } =
[
Simplify, Normalize, Expand, Factorize, Differentiate, Integrate, Limit, Substitute,
Solve, SolveSystem, SolveConjunction, Evaluate, EvaluateNumerically, Variables, Alternatives, Latex, Sympy, TruthTable, SatisfyingAssignments, Series, AreEqual,
Solve, SolveSystem, SolveConjunction, Evaluate, EvaluateNumerically, Variables, Alternatives, Latex, Sympy, Hlsl, Glsl, TruthTable, SatisfyingAssignments, Series, AreEqual,
ToBase, FromBase,
Determinant, Inverse, Transpose, Rank, ReducedRowEchelonForm, Trace, TensorProduct,
PrimeFactorization, Totient, GreatestCommonDivisor, DivisorCount, IsPrime,
Expand Down
1 change: 1 addition & 0 deletions Sources/AngouriMath/Docs/Contributing/Packaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,7 @@ subsystem's own directory.
| Gröbner bases | one inbound edge, `Functions/Continuous/Solvers/EquationSolver.cs`, and **0 public members**. Reachable from `Solve` on a system, which is a measured popular use case — **kernel** |
| Boolean minimisation | reached from `Simplificator` — **kernel** |
| compilation into LINQ | `System.Linq.Expressions` is in the framework, so (D) does not fire; measured AOT-clean — **kernel** |
| shader source, `MathS.Shaders` | string output, no new dependency (`KernelDependenciesTest`), and off every default path. It reads the compilers' own internal refusals and rewrites, so that it declines and computes what `Compile<double, …>` does, which is (C)'s test failing: it composes the kernel — **kernel** |
| quantum, and the monoid algebra it is the only consumer of | 702 lines, 0.5% of the assembly. Reached **only from `Convenience/MathS.cs`** — the facade — and by nothing in the engine. Its whole public surface is `MathS.Quantum` and its five methods. No clause fires, so the rule leaves it in the kernel; §6 says why that is the right answer despite the boundary being arguably wrong |
| `MathS.ExperimentalFeatures` | 191 lines, 12 public members, kernel. The one case where a boundary would buy something real — §6 |

Expand Down
Loading
Loading