Skip to content

Collisions - #97

Open
averybavery wants to merge 8 commits into
uwplasma:mainfrom
averybavery:collisions
Open

averybavery wants to merge 8 commits into
uwplasma:mainfrom
averybavery:collisions

Conversation

@averybavery

Copy link
Copy Markdown

This is the pull request for the work done on implementing collisions into PyPIC3D which I presented at the DPP 2026 conference. I'll go over the new code and implementation into the PIC loop, and the demos used to validate the physicality of these collisions. Much credit to Claude of course, anything not covered in my writing can probably be answered by it.

There are two collision types that have been implemented: binary collisions within the plasma and Monte Carlo collisions (MCC) with a background neutral gas. Both have a wide variety of applications which should now be observable in demos created with collisions toggled on.

To create a demo with collisions, you can either define global variables at the top of a Python file and write a "run" function as shown in the example below for relaxation due to binary collisions.

image image

Or you can create a TOML file by specifying the collision type in the following way taken from the two-stream suppression demo.

image image

Going deeper into the code, the changes can be summarized as the addition of one big collisions file and calling the "apply collisions" command right before updating all particle positions in PyPIC's time loops.

Analyzing the collisions file, we have

  • load_collisions_from_toml(config, species_name): tells the simulation the collision specification from the TOML file.

  • cross_section(value): this function is kind of unintuitive for runtime reasons but in the TOML file, the cross section is specified by a value or table. The program then linearly interpolates for the particle based on the input in the TOML. The cross section is used for later collisional equations.

  • isotropic(key, n): takes in the random key and n directions to randomize and spits out random isotropic directions. This is used in MCC collisions whereas binary collisions have a different way of scattering.

  • rotate(g, cos_t, key): this is an integral step of the binary collisions, I will detail further when analyzing them.

  • nanbu_cos(s, r): samples an angle theta from Nanbu's distribution. This is also a key part of binary collisions found to be more accurate than the initial algorithm for binary collisions introduced by the literature.

  • binary(key, x, u, active, spec, species_config, dyn): this is the command which executes binary collisions for one tile and one species pair. This is a very nuanced process which is best described by the literature (see "A binary collision model for plasma simulation with a particle code" by Takizuka and Abe, 1977). The Claude generated summary of the function is as follows:
    For one tile and one species pair (a, b); a = b means intra-species:

    1. Gather particles. Take species a, or a and b together, and tag each particle by its species.
    2. Find cells. Compute each particle’s cell index, floor(x / dx).
    3. Sort. Order the particles by active status, cell, species tag, and finally a random number. This groups each cell’s particles together in random order, which is the random pairing.
    4. Count per cell. Find where each cell’s run of particles starts and count n_a and n_b in it.
    5. Number of pairs per cell:
    • Intra-species: n/2 pairs. If n is odd (and ≥ 3), the last three particles collide pairwise (1–2, 2–3, 1–3) at half density. This is Takizuka–Abe’s rule, so every particle collides.
    • Inter-species: max(n_a, n_b) pairs, so every particle in the larger group collides once. Particles of the smaller group are reused cyclically.
    1. Pair density n_pair:
    • intra-species: w·n_a/V, halved for the odd triplet;
    • inter-species: max(w_a, w_b)·n_a·n_b/(n_max·V).
    1. List all pairs. Spread the pairs across all cells into “rounds”. Within one round no particle appears twice, so a round’s updates can be applied together.
    2. For each round (fori_loop), for each pair (i, j):
      a) Relative velocity g = u_i − u_j.
      b) Scattering parameter s = 2⟨δ²⟩, with
      ⟨δ²⟩ = q_a² q_b² n_pair lnΛ Δt / (8π ε₀² μ² |g|³) and μ = m_a m_b/(m_a + m_b).
      c) Draw cos θ from Nanbu’s distribution (_nanbu_cos), using Pérez’s fit:
      s < 0.1: small-angle limit;
      s ≥ 6: isotropic;
      otherwise: the fitted distribution.
      d) Rotate g by θ about itself, with a random azimuth φ (_rotate). |g| stays the same.
      e) Δg = g′ − g. Update u_i += (m_b/(m_a+m_b))·Δg and u_j −= (m_a/(m_a+m_b))·Δg. This conserves momentum and energy exactly.
      f) Weight correction: if the weights differ, update particle i only with probability w_b/w_max, and j only with probability w_a/w_max. Conservation then holds on average.
      g) Write the new velocities back to the species slots.

For more on binary collisions, the documentation for the open source PIC code Smilei is also really good and has a comprehensive list of the literature (https://smileipic.github.io/Smilei/Understand/collisions.html#perez2012).

  • insert(x, u, active, s, mask, xn, un): MCC collisions have 5 different outcomes, whichever of them happen is based on the value of the random draw which decides if a collision happens or not. These outcomes are charge exchange, back scattering, ionization, elastic scattering and excitation. Ionization collisions introduce new particles to arrays and JAX arrays have fixed sizes so this function gets around that.
  • mcc(key, x, u, active, spec, species_config, dyn): This is the command which executes a Monte Carlo collision. The Claude generated summary is as follows:
    For one tile and one projectile species colliding with a fixed Maxwellian gas (density n_gas, temperature T_gas, mass M):
    1. Gas partners. Draw a gas atom velocity v_n for every particle, Maxwellian at T_gas.
    2. Relative motion. g = u − v_n. Energy E = ½μ|g|² in eV, with μ = mM/(m+M).
    3. Rate of each process k: νk = n_gas · σk(E) · |g|, where σ_k(E) is interpolated from the cross-section tables.
    4. Collide or not. A particle collides this step with probability P = 1 − exp(−ν_total Δt).
    5. Which process. Pick process k with probability νk/νtotal, using one random number against the cumulative rates.
    6. Energy loss. Subtract the process’s threshold energy (excitation, ionization) from the relative motion: |g′| = √(|g|² − 2·E_thr/μ).
    7. New velocity by process:
      elastic / excitation: isotropic scatter in the centre-of-mass frame, v = v_cm + M/(m+M)·|g′|·random direction.
      back: reverse the relative velocity, v = v_cm − M/(m+M)·g.
      charge_exchange: the particle takes the neutral’s velocity, v = v_n.
      ionization: the remaining energy is split equally between the scattered and the ejected electron (|g′|/√2 each), both sent in random directions. A new electron and a new ion (moving at v_n) are created at the collision position.
    8. Insert new particles. Ionization products go into free (inactive) slots of their species (_insert). If there are no free slots, the overflow flag is set.

-apply_collisions(particles, species_config, static_parameters, dynamic_parameters): This is the command that brings it all together and performs the collisions. I do want to note here that while I understand the general idea of the tiling speedup, there are a lot of nontrivialities which come with implementing collisions in the tiled code. Apparently using jax.vmap in this function runs the collisions across all tiles at the same time, maybe it's worth looking into.

There's also this concept of overflow which has to do with a tile having more particle of a certain species than it has slots. This could happen without collisions as particles move between tiles but it also can happen due to ionization collisions now. There's handling of this but I haven't looked deeply into it as the demos presented at conference were all based on charge exchange collisions.

DEMOS: There are four collisional demos being pushed.

  • Two-stream MCC: This demo runs the same two-stream instability with collisions off and on. The plot file compares their energies and we observe that MCC can suppress a two-stream instability when toggled on.
  • MCC Maxwellianization: this demo runs MCC collisions on a uniform plasma until it becomes a Maxwellian which is a very intuitive result.
  • Binary Relaxation: This compares an analytic relaxation rate to that of the simulation for binary collisions. The graphs made by this are based on work done by Longyu Ma for collisions in JAX-in-Cell and match within 10%.
  • Relaxation: This runs the above simulation for different parameters so you can observe the final effects in a faster time. You can observe two species equilibrating to an analytic temperature. The rate at which is different from theory because theory assumes a Maxwellian for the whole evolution but if you compare to WarpX's binary collisions (shown on poster), it matches very well.

Figures and final poster below.
image

image image image

https://uwprod-my.sharepoint.com/:p:/g/personal/kahar_wisc_edu/IQDS7ltWIqMiSqxL0gBLBvVwAa94evJN2BD4_sbi5_Zm7NE?email=uwplasma%40g-groups.wisc.edu&e=j3n8uD

Finally, there's a new collisions test suite you can look at and an update to a GR test that wasn't working with collisions for some reason.

This my first PR! Don't hesitate to reach out and collaborate. Let me know what I could do better and if there's better formatting I could do.

-Avery

averybavery and others added 5 commits November 15, 2026 12:30
- PyPIC3D/collisions.py: per-cell binary Coulomb collisions (Takizuka-Abe
  pairing with Nanbu/Perez angular scattering, intra- and inter-species,
  weight-corrected) and WarpX-style background MCC (elastic, back,
  charge_exchange, excitation, ionization with product insertion).
- Configured with [collisions.<name>] TOML tables; applied after the
  velocity push in the Yee, electrostatic, and dark-matter loops.
- TiledParticles carries an optional PRNG key.
- demos/collisions: relaxation benchmarks (Maxwellianization,
  thermalization, equilibration, MCC bath) and a weakly ionized
  two-stream run.
- tests/code_tests/collisions_test.py
…ith the particle key

- demos/collisions/two_stream_mcc: collisionless and MCC TOML inputs plus plot.py,
  matching the other TOML-driven demos.
- demos/collisions/{relaxation,binary_relaxation,mcc_maxwellian}: 0-D collision
  operator checks against theory (binary_relaxation optionally compares with WarpX).
- lapse_deleting_test: compare particle leaves so the optional TiledParticles.key
  (None outside collisions) is skipped.
- collisions.py: docstring wording.
@cwoolfo1

Copy link
Copy Markdown
Member

I merged the recent state of the repository into this PR @averybavery. The unit test suite is appearing to fail and we need to diagnose and resolve those failures before merging with main.

@cwoolfo1

Copy link
Copy Markdown
Member

I have implemented some minor changes to eliminate some of the errors in the unit-test suite. It looks like the rest of the errors are due to API drift in the JAX BSSN imports for the dynamical relativity module

…jit compilation of the evolution parameters in PyPIC3D vs JAX BSSN

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants