Two-body Interactions (QED)

.gitignore

@@ -65,6 +65,7 @@ ignore-*
 tombi/
 tidy/
 .claude
+.understand-anything
 
 # devenv
 .devenv*

CODEGUIDE.md

@@ -16,7 +16,7 @@ entity
 │   ├── styling.cmake            #   styling functions
 │   └── tests.cmake              #   root cmake for tests
 ├── dev                          # developer-specific tools
-│   ├── nix                      #   nix-shells
+│   ├── nix                      #   nix-shell & devenv environments
 │   ├── runners                  #   dockerfiles for github runners on different architectures
 │   ├── scripts                  #   developer-specific scripts
 │   ├── Dockerfile.common        #   parent docker environment for development

dev/nix/adios2.nix

@@ -39,6 +39,7 @@ stdenv.mkDerivation {
   ];
 
   propagatedBuildInputs = [
+    pkgs.libgcc
     pkgs.gcc15
   ]
   ++ (

dev/nix/devenv.lock

@@ -42,4 +42,4 @@
   },
   "root": "root",
   "version": 7
-}
+}

dev/nix/kokkos.nix

@@ -27,6 +27,7 @@ let
     ];
     "NONE" = [
       pkgs.clang-tools
+      pkgs.libgcc
       pkgs.gcc15
     ];
   };

dev/scripts/format.sh

@@ -3,43 +3,43 @@
 verify=false
 
 for arg in "$@"; do
-	case $arg in
-	--verify) verify=true ;;
-	esac
+  case $arg in
+  --verify) verify=true ;;
+  esac
 done
 
 if $verify; then
-	diff_output=""
+  diff_output=""
 
-	if command -v cmake-format &>/dev/null; then
-		while IFS= read -r -d '' f; do
-			if ! diff -q <(cmake-format "$f") "$f" &>/dev/null; then
-				diff_output+="  $f\n"
-			fi
-		done < <(find cmake/ src/ minimal/ tests/ -type f \( -name "*.cmake" -o -name "*.txt" \) -print0)
-	fi
+  if command -v cmake-format &>/dev/null; then
+    while IFS= read -r -d '' f; do
+      if ! diff -q <(cmake-format "$f") "$f" &>/dev/null; then
+        diff_output+="  $f\n"
+      fi
+    done < <(find cmake/ src/ minimal/ tests/ -type f \( -name "*.cmake" -o -name "*.txt" \) -print0)
+  fi
 
-	if command -v clang-format &>/dev/null; then
-		while IFS= read -r -d '' f; do
-			if ! clang-format --style=file --dry-run --Werror "$f" &>/dev/null; then
-				diff_output+="  $f\n"
-			fi
-		done < <(find pgens/ src/ minimal/ tests/ -type f \( -name "*.cpp" -o -name "*.hpp" -o -name "*.h" \) -print0)
-	fi
+  if command -v clang-format &>/dev/null; then
+    while IFS= read -r -d '' f; do
+      if ! clang-format --style=file --dry-run --Werror "$f" &>/dev/null; then
+        diff_output+="  $f\n"
+      fi
+    done < <(find pgens/ examples/ tutorials/ src/ minimal/ tests/ -type f \( -name "*.cpp" -o -name "*.hpp" -o -name "*.h" \) -print0)
+  fi
 
-	if [ -n "$diff_output" ]; then
-		echo "Formatting check failed. The following files need formatting:"
-		printf "$diff_output"
-		exit 1
-	else
-		echo "All files are properly formatted."
-	fi
+  if [ -n "$diff_output" ]; then
+    echo "Formatting check failed. The following files need formatting:"
+    printf '%s' "$diff_output"
+    exit 1
+  else
+    echo "All files are properly formatted."
+  fi
 else
-	if command -v cmake-format &>/dev/null; then
-		find cmake/ src/ minimal/ tests/ -type f -name "*.cmake" -o -name "*.txt" | xargs cmake-format -i
-	fi
+  if command -v cmake-format &>/dev/null; then
+    find cmake/ src/ minimal/ tests/ \( -type f -name "*.cmake" -o -name "*.txt" \) -exec cmake-format -i {} \;
+  fi
 
-	if command -v clang-format &>/dev/null; then
-		find pgens/ src/ minimal/ tests/ -type f -name "*.cpp" -o -name "*.hpp" -o -name "*.h" | xargs clang-format --style=file -i
-	fi
+  if command -v clang-format &>/dev/null; then
+    find pgens/ src/ minimal/ tests/ examples/ pgens/ tutorials/ \( -type f -name "*.cpp" -o -name "*.hpp" -o -name "*.h" \) -exec clang-format --style=file -i {} \;
+  fi
 fi

entity.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://entity-toolkit.github.io/schema/entity.schema.json",
   "title": "entity",
   "description": "Entity simulation input file",
-  "$comment": "GENERATOR CONVENTION -- this schema is the single source of truth for `input.template.toml`. Standard keywords carry the machine-checkable part (type/enum/minimum/maximum/items/prefixItems/minItems/maxItems/pattern/default/required/deprecated). The `x-entity` object carries the parts JSON Schema cannot express, all verbatim from the template comments: `type` = the literal `@type:` annotation (use it for the comment line whenever present, else derive from the standard keywords); `default` = the literal `@default:` annotation (use it whenever present, else format the standard `default`); `notes` = ordered `@note:` lines; `examples` = ordered `@example:` lines; `enum` = an illustrative, NON-exhaustive value list that must not be validated as a real `enum`; `deprecated` = the `@deprecated:` text. `x-entity.inferred` on an object lists quantities the code derives rather than reads; they are NOT valid input keys (so they are absent from `properties` and rejected by `additionalProperties: false`) and should be emitted as an `@inferred:` comment block after that table's own keys and before its sub-tables. Property order in `properties` is the emission order. Objects with `additionalProperties: true` are free-form. `$ref` is used once, for `$defs/colormap`.",
+  "$comment": "GENERATOR CONVENTION -- this schema is the single source of truth for `input.default.toml`. Standard keywords carry the machine-checkable part (type/enum/minimum/maximum/items/prefixItems/minItems/maxItems/pattern/default/required/deprecated). The `x-entity` object carries the parts JSON Schema cannot express, all verbatim from the template comments: `type` = the literal `@type:` annotation (use it for the comment line whenever present, else derive from the standard keywords); `default` = the literal `@default:` annotation (use it whenever present, else format the standard `default`); `notes` = ordered `@note:` lines; `examples` = ordered `@example:` lines; `enum` = an illustrative, NON-exhaustive value list that must not be validated as a real `enum`; `deprecated` = the `@deprecated:` text. `x-entity.inferred` on an object lists quantities the code derives rather than reads; they are NOT valid input keys (so they are absent from `properties` and rejected by `additionalProperties: false`) and should be emitted as an `@inferred:` comment block after that table's own keys and before its sub-tables. Property order in `properties` is the emission order. Objects with `additionalProperties: true` are free-form. `$ref` is used once, for `$defs/colormap`.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -844,6 +844,100 @@
         }
       }
     },
+    "two_body": {
+      "description": "Parameters for two-body interactions",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "thomson_optical_depth": {
+          "description": "Nominal Thomson optical depth: `tau = n0 * sigma_T * 1` over a distance of 1 in physical units (n0 = nominal density)",
+          "type": "number",
+          "exclusiveMinimum": 0.0,
+          "default": 1.0
+        },
+        "interaction": {
+          "description": "Specific interaction parameters",
+          "type": "array",
+          "minItems": 1,
+          "x-entity": {
+            "array_of_tables": true
+          },
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "type",
+              "group1"
+            ],
+            "properties": {
+              "type": {
+                "description": "Type of the two-body interaction",
+                "anyOf": [
+                  {
+                    "enum": [
+                      "Compton"
+                    ]
+                  },
+                  {
+                    "type": "string",
+                    "pattern": "(?i)^(Compton)$"
+                  }
+                ],
+                "x-entity": {
+                  "type": "string"
+                }
+              },
+              "group1": {
+                "description": "First group of species indices participating in the interaction",
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "integer",
+                  "minimum": 1
+                }
+              },
+              "group2": {
+                "description": "Second group of species indices participating in the interaction",
+                "type": "array",
+                "minItems": 0,
+                "default": [],
+                "x-entity": {
+                  "notes": [
+                    "For interactions between particles of the same group, leave `group2` empty"
+                  ]
+                },
+                "items": {
+                  "type": "integer",
+                  "minimum": 1
+                }
+              },
+              "interval": {
+                "description": "Interval in timesteps between checking for the interaction",
+                "type": "integer",
+                "minimum": 1,
+                "default": 1
+              },
+              "tile_size": {
+                "description": "Size of interaction tile in cells",
+                "type": "integer",
+                "minimum": 1,
+                "default": 4
+              },
+              "recoil1": {
+                "description": "Whether to apply recoil to the first group of particles",
+                "type": "boolean",
+                "default": true
+              },
+              "recoil2": {
+                "description": "Whether to apply recoil to the second group of particles",
+                "type": "boolean",
+                "default": true
+              }
+            }
+          }
+        }
+      }
+    },
     "algorithms": {
       "description": "Algorithm and solver tuning",
       "type": "object",
@@ -1650,7 +1744,7 @@
             "e_min": {
               "description": "Minimum energy for the spectra output",
               "type": "number",
-              "exclusiveMinimum": 0.0,
+              "minimum": 0.0,
               "default": 0.001,
               "x-entity": {
                 "type": "float",

examples/compton_jones/compton_jones.py

@@ -0,0 +1,63 @@
+import nt2
+import matplotlib.pyplot as plt
+import numpy as np
+
+data = nt2.Data("compton_jones")
+
+photons = data.particles.sel(sp=3).isel(t=-1).load()
+photons = photons[np.sqrt(photons.ux**2 + photons.uy**2 + photons.uz**2) > 0.01]
+
+plt.rcParams["figure.dpi"] = 300
+plt.rcParams["font.family"] = "serif"
+plt.rcParams["mathtext.fontset"] = "stix"
+
+fig = plt.figure(figsize=(9, 4))
+gs = fig.add_gridspec(1, 2, wspace=0.35)
+ax1 = fig.add_subplot(gs[0, 0])
+ax2 = fig.add_subplot(gs[0, 1])
+
+gamma = np.sqrt(1 + data.attrs["setup.electron_4vel"] ** 2)
+e0 = data.attrs["setup.photon_energy"]
+Gamma = 4 * e0 * gamma
+emax = gamma * Gamma / (1 + Gamma)
+
+es = data.spectra.E[1:-1] / emax
+
+dnde = data.spectra.N_3.isel(t=-1)[1:-1]
+dnde /= np.trapezoid(dnde, es)
+ax1.plot(es, dnde)
+
+es = np.linspace(es.values.min(), es.values.max(), 250)
+qs = es / (1 + Gamma * (1 - es))
+dnde_th = (
+    2 * qs * np.log(qs)
+    + (1 + 2 * qs) * (1 - qs)
+    + 0.5 * Gamma**2 * qs**2 / (1 + Gamma * qs) * (1 - qs)
+)
+
+dnde_th /= np.trapezoid(dnde_th, es)
+
+ax1.plot(es, dnde_th, c="k", ls=":")
+ax1.set(
+    xlim=(0, 1),
+    ylim=(0, 4),
+    xlabel=r"$\varepsilon_{\rm ph} / \varepsilon_{\rm max}$",
+    ylabel=r"$dn_{\rm ph}/d\varepsilon_{\rm ph}$",
+)
+
+plt.scatter(
+    photons.ux / emax,
+    photons.uy / emax,
+    s=1,
+    linewidth=0,
+)
+xs = np.linspace(0, 1, 100)
+ys = 2 / gamma * xs
+ax2.plot(xs, ys, c="k", ls="--", lw=0.5)
+ax2.plot(xs, -ys, c="k", ls="--", lw=0.5)
+ax2.set(
+    xlabel=r"$p_{\rm ph}^x / \varepsilon_{\rm max}$",
+    ylabel=r"$p_{\rm ph}^y / \varepsilon_{\rm max}$",
+)
+
+plt.savefig("compton_jones.png", bbox_inches="tight")

examples/compton_jones/compton_jones.toml

@@ -0,0 +1,89 @@
+[simulation]
+  name    = "compton_jones"
+  engine  = "srpic"
+  runtime = 10.0
+
+[grid]
+  resolution = [32, 32]
+  extent     = [[0.0, 1.0], [0.0, 1.0]]
+
+  [grid.metric]
+    metric = "minkowski"
+
+  [grid.boundaries]
+    fields    = [["PERIODIC"], ["PERIODIC"]]
+    particles = [["PERIODIC"], ["PERIODIC"]]
+
+[scales]
+  larmor0    = 1.0
+  skindepth0 = 1.0
+
+[two_body]
+  thomson_optical_depth = 100.0
+
+  [[two_body.interaction]]
+    type      = "compton"
+    group1    = [1]
+    group2    = [2]
+    interval  = 1
+    tile_size = 5
+    recoil1   = false
+    recoil2   = true
+
+[algorithms]
+  current_filters = 0
+
+  [algorithms.deposit]
+    enable = false
+
+  [algorithms.fieldsolver]
+    enable = false
+
+[particles]
+  ppc0           = 5.0
+  clear_interval = 1
+
+  [[particles.species]]
+    label    = "e-"
+    mass     = 1.0
+    charge   = -1.0
+    maxnpart = 1e6
+
+  [[particles.species]]
+    label    = "ph"
+    mass     = 0.0
+    charge   = 0.0
+    maxnpart = 1e6
+
+  [[particles.species]]
+    label    = "ph_out"
+    mass     = 0.0
+    charge   = 0.0
+    maxnpart = 1e7
+    pusher   = "none"
+
+[setup]
+  electron_4vel = 999.9995
+  photon_energy = 1e-2
+
+[output]
+  interval_time = 9.0
+
+  [output.fields]
+    quantities = ["N_1", "N_2", "N_3"]
+
+  [output.particles]
+    species = [1, 2, 3]
+    stride  = 1
+
+  [output.spectra]
+    log_bins = false
+    e_min    = 0
+    e_max    = 1100
+    n_bins   = 100
+
+  [output.stats]
+    quantities = ["T00_1", "T00_2", "T00_3"]
+
+[checkpoint]
+  keep = 0