Skip to content

Investigate a Symbolics.jl-first operator architecture #53

Closed as not planned

Description

@kylebeggs

Motivation

MatrixFreeOperators.jl currently composes a typed lazy operator tree, but its primitive leaves, traits, adjoints, and linearization behavior are authored explicitly in Julia. “Symbolic composition” therefore stops at the package's own algebra: users cannot start from a general Symbolics.jl PDE expression, and new mathematical forms still require package-specific plumbing.

Investigate making Symbolics.jl a first-class source-level representation from which MatrixFreeOperators lowers to its existing field, grid, halo, boundary, and device execution model. The symbolic layer should improve authoring, simplification, differentiation, and SciML interoperability without weakening the package's matrix-free, allocation-free, or device-agnostic contracts.

Companion investigation: JuliaMeshless/RadialBasisFunctions.jl#155

Working architectural hypothesis

Symbolics.jl should own continuous mathematical intent; MatrixFreeOperators.jl's existing typed lazy tree should remain the discrete operator IR and continue to own grids, field ranks, boundary treatment, halo exchange, device placement, preparation, and discrete adjoints.

Symbolics expression → discretization-aware lowering → typed operator tree → prepared matrix-free kernels

Known forms should lower to existing leaves and algebra. Generated fused leaves should be an escape hatch for expressions the tree cannot represent faithfully, not the default. Symbolics objects must disappear before apply!, mul!, and prepared solver paths.

This separation mirrors the useful part of MethodOfLines.jl's architecture: symbolic terms are recognized first, while discretization and boundary handling remain explicit later stages.

Proposed investigation

  1. Define a symbolic vocabulary for fields, coordinates, coefficients, derivatives, nonlinear terms, and boundary operators.
  2. Prototype lowering common symbolic expressions into the existing AbstractOperator leaves and lazy algebra, generating a fused leaf only where the current tree cannot express the operation faithfully.
  3. Evaluate which properties can be derived or checked from the symbolic representation: linearity, constancy, rank changes, continuous adjoints, parameter derivatives, and Jacobians/JVPs.
  4. Preserve the distinction between continuous symbolic identities and the discrete adjoint, whose correctness depends on halo exchange and boundary treatment; verify generated operators with the existing dot-product identity.
  5. Define a constrained rewrite policy that preserves discretization-significant forms rather than applying unrestricted symbolic simplification before lowering.
  6. Decide how Symbolics.jl relates to the current public constructors, linearize, package extensions, and any future ModelingToolkit integration.

Key semantic constraint

Symbolic manipulation and discretization do not generally commute. For example, the continuous identity

∇·(κ∇u) = κΔu + ∇κ·∇u

does not guarantee identical discrete operators. Lowering the divergence form as divergence(g) * scaling(κ) * gradient(g) may preserve flux conservation, while expanding it first may not. The same concern applies to continuous adjoints: boundary conditions, halo exchange, and the chosen stencil determine the correct discrete transpose.

Symbolics' tracing documentation also notes that symbolic tracing may redistribute or reorder arithmetic. The investigation therefore needs an explicit policy for which rewrites are safe before discretization, which are allowed only after a scheme is selected, and which are forbidden.

Key risks to validate

  • Loss of discretization semantics: Unrestricted expansion or simplification can erase conservative, flux, upwind, or boundary-significant structure.
  • False adjoint confidence: A mathematically valid continuous adjoint may still be the wrong discrete adjoint.
  • Generated-code opacity: Automatically generated kernels may be harder to inspect, debug, specialize, and maintain than the current typed leaves.
  • Compiler and device integration: Generated functions must preserve type stability, GPU compatibility, allocation behavior, and Reactant/AD expectations.
  • Scope creep: Accepting arbitrary PDE systems, domains, boundary equations, and scheme selection would recreate MethodOfLines instead of strengthening this package's matrix-free execution niche.
  • Dependency cost: First-use latency, precompilation, invalidations, and extension loading must be justified by user-facing value.

Success criteria

  • A proof of concept lowers a Laplacian, ∇·(κ∇u), and one nonlinear residual into executable matrix-free operators.
  • Recognized expressions lower to the existing typed leaves and algebra wherever possible; the prototype records why any generated leaf is necessary.
  • The lowered operators match the current implementations on CPU and GPU, including boundary behavior and parameter gradients.
  • The variable-coefficient diffusion prototype preserves divergence form through lowering and demonstrates the numerical consequences of any allowed alternative rewrite.
  • Linearization produces a JVP consistent with the existing finite-difference and Enzyme paths, and linear operators satisfy the discrete adjoint dot-product identity.
  • prepare remains zero-allocation in steady state, symbolic objects do not enter hot loops, and compilation/construction overhead is quantified.
  • A short architecture decision recommends whether Symbolics.jl should be a core dependency or extension and gives a staged migration plan for existing leaves.

Out of scope

  • Replacing the current Field, grid, halo-exchange, AMR, or distributed execution layers.
  • Switching to assembled sparse matrices or implementing a full MethodOfLines/ModelingToolkit discretizer.
  • Assuming a continuous symbolic adjoint is automatically the correct discrete adjoint.
  • Replacing the existing typed operator tree with Symbolics expression objects.

Open questions

  • Is Symbolics.jl best treated as the canonical frontend/IR with MatrixFreeOperators as the lowering backend, or should symbolic types also appear directly in the public operator API?
  • Which expressions should lower to existing composable leaves, and which justify generated fused kernels?
  • How should symbolic coefficient fields retain device placement, mutability, and differentiation semantics after lowering?
  • Which symbolic rewrites preserve the intended discretization, and how should packages attach “do not expand” or scheme-selection metadata to expressions?
  • Is there a genuinely reusable symbolic seam with RadialBasisFunctions.jl, or should both packages keep independent lowering layers until the common abstraction is proven?

🤖 Claude sketched this operator graph; Kyle has not become his own mysterious reviewer.

Activity

  1. kylebeggs commented on Sep 30, 2026

    @kylebeggs
    CollaboratorAuthor

    Closing as not planned. A Symbolics.jl-first architecture would be a cross-package redesign with no current consumer. The dependency rule already answers the narrower question: any Symbolics integration would be an ext/, never core, because core stays at Adapt / KernelAbstractions / LinearAlgebra / StaticArrays / AcceleratedKernels. Reopen if a concrete use case (e.g. generating stencils from symbolic PDEs) appears.

    —
    🤖 Claude closing this one. The operators remain stubbornly numeric.
    claude-opus-5-5[1m] (high) · claude-code 2.1.285 · unreviewed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    questionFurther information is requested

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions