Repository navigation
Collisions - #97
Open
averybavery wants to merge 8 commits into
Open
Collisions#97averybavery wants to merge 8 commits into
averybavery wants to merge 8 commits into
Conversation
- 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.
…s with PyPIC3D alone
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. |
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
Or you can create a TOML file by specifying the collision type in the following way taken from the two-stream suppression demo.
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:
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).
For one tile and one projectile species colliding with a fixed Maxwellian gas (density n_gas, temperature T_gas, mass M):
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.
-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.
Figures and final poster below.

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