Simultipac 2.0.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,98 @@
1
+ """Define functions to be used everywhere in the subpackage."""
2
+
3
+ import numpy as np
4
+
5
+
6
+ def triangles_ray_intersections(
7
+ origin: np.ndarray,
8
+ direction: np.ndarray,
9
+ m_mesh: int,
10
+ edges_1: np.ndarray,
11
+ edges_2: np.ndarray,
12
+ vertices_1: np.ndarray,
13
+ normals: np.ndarray,
14
+ eps: float,
15
+ ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
16
+ """Detect collision between a single ray and several triangles of mesh.
17
+
18
+ Based on `Möller–Trumbore intersection algorithm`_. Stolen and adapted from
19
+ `printrun`_ library. Parallel implementation taken from `@V0XNIHILI`_.
20
+
21
+ .. _`Möller–Trumbore intersection algorithm`: https://en.wikipedia.org/wik\
22
+ i/M%C3%B6ller%E2%80%93Trumbore_intersection_algorithm
23
+ .. _printrun: https://github.com/kliment/Printrun/blob/master/printrun/\
24
+ stltool.py#L47
25
+ .. _@V0XNIHILI: https://gist.github.com/V0XNIHILI/\
26
+ 87c986441d8debc9cd0e9396580e85f4
27
+
28
+ Parameters
29
+ ----------
30
+ origin : np.ndarray(3, )
31
+ Holds the starting point of the ray.
32
+ direction : np.ndarray(3, )
33
+ Holds the direction of the ray.
34
+ m_mesh : int
35
+ Number of triangles under study.
36
+ edges_1 : np.ndarray(m_mesh, 3)
37
+ The first edge of every triangle.
38
+ edges_2 : np.ndarray(m_mesh, 3)
39
+ The second edge of every triangle.
40
+ vertices_1 : np.ndarray(m_mesh, 3)
41
+ The junction point of ``edges_1`` and ``edges_2`` for every triangle.
42
+ normals : np.ndarray(m_mesh, 3)
43
+ Normal vector of every triangle.
44
+ eps : float
45
+ Tolerance.
46
+
47
+ Returns
48
+ -------
49
+ collisions : np.ndarray(m_mesh, )
50
+ Array of booleans telling if there was a collision or not.
51
+ distances : np.ndarray(m_mesh, )
52
+ Array of floats giving distance between ``origin`` and the triangle.
53
+ impact_angles : np.ndarray(m_mesh, )
54
+ Holds the impact angles in radians, or a nan.
55
+
56
+ """
57
+ collisions = np.full((m_mesh), True)
58
+ distances = np.zeros(m_mesh)
59
+ impact_angles = np.full((m_mesh), np.nan)
60
+
61
+ # Check if intersection line/plane or if they are just parallel
62
+ pvec = np.cross(direction, edges_2)
63
+ triple_products = np.sum(edges_1 * pvec, axis=1)
64
+ no_collision_idx = np.absolute(triple_products) < eps
65
+ collisions[no_collision_idx] = False
66
+ distances[no_collision_idx] = np.nan
67
+
68
+ inv_triple_prod = 1.0 / triple_products
69
+
70
+ # First axis: check if intersection triangle/line or just plane/line
71
+ tvec = origin - vertices_1
72
+ u_coord = np.sum(tvec * pvec, axis=1) * inv_triple_prod
73
+ no_collision_idx = (u_coord < 0.0) + (u_coord > 1.0)
74
+ collisions[no_collision_idx] = False
75
+ distances[no_collision_idx] = np.nan
76
+
77
+ # Second axis: check if intersection triangle/line or just plane/line
78
+ qvec = np.cross(tvec, edges_1)
79
+ v_coord = np.sum(direction * qvec, axis=1) * inv_triple_prod
80
+ no_collision_idx = (v_coord < 0.0) + (u_coord + v_coord > 1.0)
81
+ collisions[no_collision_idx] = False
82
+ distances[no_collision_idx] = np.nan
83
+
84
+ # Check if intersection triangle/trajectory or just triangle/line
85
+ distance = np.sum(edges_2 * qvec, axis=1) * inv_triple_prod
86
+ no_collision_idx = distance < eps
87
+ collisions[no_collision_idx] = False
88
+ distances[no_collision_idx] = np.nan
89
+
90
+ distances[collisions] = distance[collisions]
91
+
92
+ # To compute angle
93
+ adjacents = normals[collisions].dot(direction)
94
+ opposites = np.linalg.norm(np.cross(normals[collisions], direction))
95
+ tan_theta = opposites / adjacents
96
+ impact_angles[collisions] = np.abs(np.arctan(tan_theta))
97
+
98
+ return collisions, distances, impact_angles
@@ -0,0 +1,38 @@
1
+ """Define functions to study collisions with a ``Mesh`` from ``vedo`` package.
2
+
3
+ For that we use the ``vedo`` built-in methods.
4
+
5
+ """
6
+
7
+ import numpy as np
8
+ import vedo
9
+
10
+
11
+ def part_mesh_intersections(
12
+ origin_segment: np.ndarray,
13
+ end_segment: np.ndarray,
14
+ structure: vedo.Mesh,
15
+ eps: float = 1e-6,
16
+ ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
17
+ """
18
+ Get all intersections between particles and complete mesh.
19
+
20
+ Parameters
21
+ ----------
22
+ structure : vedo.Mesh
23
+ An object with triangular cells.
24
+ eps : float, optional
25
+ Tolerance, optional. The default is 1e-6.
26
+
27
+ Returns
28
+ -------
29
+ all_collisions : np.ndarray[bool](n, m)
30
+ Indicates where there was collisions.
31
+ all_distances : np.ndarray(n, m)
32
+ Indicates distances between collisions and ``origins``.
33
+ impact_angles : np.ndarray(n, m)
34
+ Impact angle of every particle with every mesh cell (is np.nan if there
35
+ was no collision).
36
+
37
+ """
38
+ pass
@@ -0,0 +1,87 @@
1
+ """Define the functions to convert momentum and speeds."""
2
+
3
+ import numpy as np
4
+ from numpy._typing import NDArray
5
+
6
+ from simultipac.constants import clight, clight_in_mm_per_ns
7
+
8
+
9
+ def adim_momentum_to_speed_m_per_s(
10
+ mom: NDArray[np.float64],
11
+ ) -> NDArray[np.float64]:
12
+ """Convert adim momentum to speed in :unit:`m/s`.
13
+
14
+ From the Position Monitor files header:
15
+
16
+ .. note::
17
+ Momentum is normalized to the product of particle's mass and speed of
18
+ light.
19
+
20
+ So ``mom`` is adimensional: normalisation = mass * clight
21
+ And we de-normalize with:
22
+ momentum_in_kg_m_per_s = ``mom`` * normalisation
23
+ speed_in_m_per_s = momentum_in_kg_m_per_s / mass = ``mom`` * clight
24
+
25
+ Parameters
26
+ ----------
27
+ mom : numpy.ndarray
28
+ A 1D or 2D array holding adimensionned momentum along the three
29
+ directions of one or several particles.
30
+
31
+ Returns
32
+ -------
33
+ speed_in_m_per_s : numpy.ndarray
34
+ A 2D array holding the speed along the three directions of one or
35
+ several particles.
36
+
37
+ """
38
+ if len(mom.shape) == 1:
39
+ mom = np.expand_dims(mom, 0)
40
+ speed_in_m_per_s = mom * clight
41
+ return speed_in_m_per_s
42
+
43
+
44
+ def adim_momentum_to_speed_mm_per_ns(
45
+ mom: NDArray[np.float64],
46
+ force_2d: bool = True,
47
+ ) -> NDArray[np.float64]:
48
+ """Convert adimensionned momentum to speed in :unit:`mm/ns`.
49
+
50
+ Parameters
51
+ ----------
52
+ mom : numpy.ndarray
53
+ A 1D or 2D array holding adimensionned momentum along the three
54
+ directions of one or several particles.
55
+ force_2d : bool, optional
56
+ Force output array in 2D.
57
+
58
+ Returns
59
+ -------
60
+ speed_in_mm_per_ns : numpy.ndarray
61
+ A 1D or 2D array holding the speed along the three directions of one or
62
+ several particles.
63
+
64
+ """
65
+ if len(mom.shape) == 1 and force_2d:
66
+ mom = np.expand_dims(mom, 0)
67
+ speed_in_mm_per_ns = mom * clight_in_mm_per_ns
68
+ return speed_in_mm_per_ns
69
+
70
+
71
+ def adim_momentum_to_eV(mom: NDArray[np.float64], mass_eV: float) -> float:
72
+ """Convert adimensionned momentum to energy in :unit:`eV`.
73
+
74
+ Parameters
75
+ ----------
76
+ mom : numpy.ndarray
77
+ A 1D or 2D array holding adimensionned momentum along the three
78
+ directions of one particle.
79
+
80
+ Returns
81
+ -------
82
+ energy : float
83
+ The energy of the particle in :unit:`eV`.
84
+
85
+ """
86
+ energy = 0.5 * float(np.linalg.norm(mom)) ** 2 * mass_eV
87
+ return energy
@@ -0,0 +1,416 @@
1
+ """Define :class:`Particle`, created by reading CST ParticleMonitor files."""
2
+
3
+ import logging
4
+ import math
5
+ from typing import Any
6
+
7
+ import numpy as np
8
+ import vedo
9
+ from numpy.typing import NDArray
10
+
11
+ from simultipac.constants import clight, qelem
12
+ from simultipac.particle_monitor.vector import Momentum, Position
13
+ from simultipac.plotter.plotter import Plotter
14
+
15
+ PartMonLine = tuple[str, str, str, str, str, str, str, str, str, str, str, str]
16
+ PartMonData = tuple[
17
+ float,
18
+ float,
19
+ float,
20
+ float,
21
+ float,
22
+ float,
23
+ float,
24
+ float,
25
+ float,
26
+ float,
27
+ int,
28
+ int,
29
+ ]
30
+
31
+
32
+ class Particle: # pylint: disable=too-many-instance-attributes
33
+ """Holds evolution of position and adim momentum with time.
34
+
35
+ Position in :unit:`mm`, time in :unit:`ns`.
36
+
37
+ Attributes
38
+ ----------
39
+ position :
40
+ Position of the particle during the simulation.
41
+ momentum :
42
+ Momentum of the particle during the simulation.
43
+ _masses :
44
+ Mass of particle at each time step. An error is raised if it changes
45
+ between two files.
46
+ mass :
47
+ Mass of the particle in :unit:`kg`.
48
+ mass_eV :
49
+ Mass of the particle in :unit:`eV`.
50
+ _charges :
51
+ Charge of particle at each time step. An error is raised if it changes
52
+ between two files.
53
+ charge :
54
+ Charge of the particle.
55
+ time :
56
+ Holds the time steps in :unit:`ns` corresponding to every value of
57
+ ``pos``, ``mom``, etc.
58
+ particle_id :
59
+ Unique id for the particle.
60
+ source_id :
61
+ Gives information on how the particle was created.
62
+ extrapolated_times :
63
+ Times at which position and momentum are extrapolated.
64
+
65
+ """
66
+
67
+ def __init__(self, raw_line: PartMonLine) -> None:
68
+ """Init from a line of a position_monitor file."""
69
+ self.extrapolated_times: np.ndarray | None = None
70
+
71
+ self._masses: list[float]
72
+ self.mass: float
73
+ self.mass_eV: float # pylint: disable=invalid-name
74
+ self._charges: list[float]
75
+ self.charge: float
76
+ self._macro_charge: list[float]
77
+ self._time: list[float]
78
+ self.time: NDArray[np.float64]
79
+ self.particle_id: int
80
+ self.source_id: int
81
+
82
+ _line = _str_to_correct_types(raw_line)
83
+ self.position = Position((_line[0],), (_line[1],), (_line[2],))
84
+ self.momentum = Momentum((_line[3],), (_line[4],), (_line[5],))
85
+ self._masses = [_line[6]]
86
+ self._charges = [_line[7]]
87
+ self._macro_charge = [_line[8]]
88
+ self._time = [_line[9]]
89
+ self.particle_id = _line[10]
90
+ self.source_id = _line[11]
91
+
92
+ self.alive_at_end = False
93
+ self.emission_cell_id: np.ndarray = np.array([], dtype=np.float64)
94
+ self.emission_point: np.ndarray = np.array([], dtype=np.uint32)
95
+ self.emission_angle: float = np.nan
96
+ self.collision_cell_id: np.ndarray = np.array([], dtype=np.uint32)
97
+ self.collision_point: np.ndarray = np.array([], dtype=np.float64)
98
+ self.collision_angle: float = np.nan
99
+
100
+ def add_a_file(self, raw_line: PartMonLine) -> None:
101
+ """Add a time-step/a file to the current Particle."""
102
+ line = _str_to_correct_types(raw_line)
103
+ self.position.append(line[0:3])
104
+ self.momentum.append(line[3:6])
105
+ self._masses.append(line[6])
106
+ self._charges.append(line[7])
107
+ self._macro_charge.append(line[8])
108
+ self._time.append(line[9])
109
+
110
+ def finalize(self) -> None:
111
+ """Post treat object for consistency checks, better data types."""
112
+ self._check_constanteness_of_some_attributes()
113
+ self.time = np.array(self._time)
114
+ self._switch_to_mm_ns_units()
115
+ if not _is_sorted(self.time):
116
+ self._sort_by_increasing_time_values()
117
+
118
+ def _check_constanteness_of_some_attributes(self) -> None:
119
+ """Ensure that mass and charge did not evolve during simulation."""
120
+ self.mass = _get_constant(self._masses)
121
+ self.mass_eV = self.mass * clight**2 / qelem
122
+ self.charge = _get_constant(self._charges)
123
+
124
+ @property
125
+ def macro_charge(self) -> NDArray[np.float64]:
126
+ """Return macro charge as an array."""
127
+ return np.array(self._macro_charge)
128
+
129
+ def _switch_to_mm_ns_units(self) -> None:
130
+ """Change the system units to limit rounding errors.
131
+
132
+ .. warning::
133
+ In CST Particle Monitor files, the time is given in seconds *
134
+ 1e-18 (aka nano-nanoseconds). Tested with CST units for time in
135
+ nanoseconds.
136
+
137
+ """
138
+ self.position.normalize()
139
+ self.time *= 1e18
140
+
141
+ def _sort_by_increasing_time_values(self) -> None:
142
+ """Sort arrays by increasing time values."""
143
+ idx = np.argsort(self.time)
144
+
145
+ self.position.reorder(idx)
146
+ self.momentum.reorder(idx)
147
+ self._macro_charge = [self._macro_charge[i] for i in idx]
148
+ self.time = self.time[idx]
149
+
150
+ @property
151
+ def emission_energy(self) -> float:
152
+ """Compute emission energy in :unit:`eV`."""
153
+ return self.momentum.emission_energy(self.mass_eV)
154
+
155
+ @property
156
+ def collision_energy(self) -> float:
157
+ """Determine the impact energy in :unit:`eV`.
158
+
159
+ Returns
160
+ -------
161
+ energy: float
162
+ The last known energy in :unit:`eV`.
163
+
164
+ """
165
+ return self.momentum.collision_energy(self.mass_eV)
166
+
167
+ def extrapolate_pos_and_mom_one_time_step_further(self) -> None:
168
+ """Extrapolate position and momentum by one time step.
169
+
170
+ CST PIC solves the motion with a leapfrog solver (source: Mohamad
171
+ Houssini from Keonys, private communication).
172
+ Several possibilities:
173
+ - ``pos`` corresponds to ``time`` and ``mom`` shifted by half
174
+ time-steps (most probable).
175
+ - ``mom`` corresponds to ``time`` and ``pos`` shifted by half
176
+ time-steps (also possible).
177
+ - ``pos`` or ``mom`` is interpolated so that both are expressed at
178
+ full ``time`` steps (what I will consider for now).
179
+
180
+ """
181
+ n_extrapolated_points = 2
182
+ n_extrapolated_time_steps = 10
183
+
184
+ self.extrapolated_times = np.full(n_extrapolated_points, np.nan)
185
+
186
+ if self.time.shape[0] <= 1:
187
+ return
188
+
189
+ fit_end = self.time[-1]
190
+ time_step = self.time[-1] - self.time[-2]
191
+ extrapolated_time_end = fit_end + n_extrapolated_time_steps * time_step
192
+ self.extrapolated_times = np.linspace(
193
+ fit_end, extrapolated_time_end, n_extrapolated_points
194
+ )
195
+
196
+ delta_t = self.extrapolated_times - fit_end
197
+ self.position.extrapolate(self.momentum, delta_t)
198
+
199
+ n_time_steps_for_polynom_fitting = 3
200
+ poly_fit_deg = 2
201
+
202
+ if poly_fit_deg >= n_time_steps_for_polynom_fitting:
203
+ raise OSError(
204
+ f"You need at least {poly_fit_deg + 1} momentum and "
205
+ "time step(s) to extrapolate momentum with a degree "
206
+ f"{poly_fit_deg} polynom."
207
+ )
208
+
209
+ if n_time_steps_for_polynom_fitting > self.time.shape[0]:
210
+ return
211
+
212
+ self.momentum.extrapolate(
213
+ self.time,
214
+ self.extrapolated_times,
215
+ poly_fit_deg,
216
+ n_time_steps_for_polynom_fitting,
217
+ )
218
+
219
+ def determine_if_alive_at_end(
220
+ self, max_time: float, tol: float = 1e-6
221
+ ) -> None:
222
+ """Determine if the particle collisioned before end of simulation.
223
+
224
+ This method sets :attr:`.alive_at_end` flag.
225
+
226
+ Parameters
227
+ ----------
228
+ max_time :
229
+ Simulation end time in :unit:`ns`.
230
+ tol :
231
+ Tolerance in :unit:`ns`.
232
+
233
+ """
234
+ if abs(max_time - self.time[-1]) < tol:
235
+ self.alive_at_end = True
236
+
237
+ def find_collision(
238
+ self,
239
+ mesh: vedo.Mesh,
240
+ warn_no_collision: bool = True,
241
+ warn_multiple_collisions: bool = False,
242
+ **kwargs,
243
+ ) -> None:
244
+ """Find where the trajectory impacts the structure.
245
+
246
+ If the particle is alive at the end of the simulation, we do not even
247
+ try. If it has only one known time step, neither do we.
248
+
249
+ We first try to detect a collision between the last known position of
250
+ the particle and the last extrapolated position. If no collision is
251
+ found, we try to find it between the last known position and the
252
+ know position just before that.
253
+
254
+ .. note::
255
+ If the last extrapolated position is too far from the last known
256
+ position, several collisions may be detected.
257
+
258
+ .. todo::
259
+ Take only nearest cell instead of the one with the lowest ID as for
260
+ now.
261
+
262
+ Parameters
263
+ ----------
264
+ mesh :
265
+ ``vedo`` mesh object describing the structure of the rf system.
266
+ warn_no_collision :
267
+ If True, a warning is raised when the electron was not alive at the
268
+ end of the simulation, but no collision was detected. The default
269
+ is True.
270
+ warn_multiple_collisions :
271
+ To warn if several collisions were detected for the same particle.
272
+ Also remove all collisions but the first one. The default is True.
273
+ kwargs :
274
+ kwargs
275
+
276
+ """
277
+ if self.alive_at_end:
278
+ return
279
+ if self.position.n_steps <= 1:
280
+ return
281
+
282
+ p_0 = self.position.last
283
+ assert self.position.extrapolated is not None
284
+ p_1 = self.position.extrapolated[-1]
285
+
286
+ collision_point, collision_cell = mesh.intersect_with_line(
287
+ p0=p_0, p1=p_1, return_ids=True, tol=0
288
+ )
289
+
290
+ if collision_point.shape[0] == 0:
291
+ if self.position.n_steps <= 2:
292
+ return
293
+ p_1 = p_0
294
+ p_0 = self.position.array[-2, :]
295
+ collision_point, collision_cell = mesh.intersect_with_line(
296
+ p0=p_0, p1=p_1, return_ids=True, tol=0
297
+ )
298
+
299
+ if warn_no_collision and collision_point.shape[0] == 0:
300
+ logging.info(f"No collision for particle {self.particle_id}.")
301
+ return
302
+
303
+ if collision_point.shape[0] > 1:
304
+ collision_point = collision_point[0, :]
305
+ collision_cell = collision_cell[0, np.newaxis]
306
+ if warn_multiple_collisions:
307
+ logging.warning(
308
+ "More than one collision for particle "
309
+ f"{self.particle_id}. Only considering the first."
310
+ )
311
+
312
+ self.collision_cell_id = collision_cell
313
+ self.collision_point = collision_point
314
+ return
315
+
316
+ def compute_emission_angle(self, mesh: vedo.Mesh) -> None:
317
+ """Compute the angle of emission."""
318
+ raise NotImplementedError
319
+ if self.collision_cell_id.shape[0] < 1:
320
+ return
321
+
322
+ direction = self.momentum.first
323
+ normal = mesh.cell_normals[self.emission_cell_id]
324
+ adjacent = normal.dot(direction)
325
+ opposite = np.linalg.norm(np.cross(normal, direction))
326
+ tan_theta = opposite / adjacent
327
+ self.emission_angle = abs(math.atan(tan_theta))
328
+
329
+ def compute_collision_angle(self, mesh: vedo.Mesh) -> None:
330
+ """Compute the angle of impact."""
331
+ if self.alive_at_end:
332
+ return
333
+ if self.collision_cell_id.shape[0] < 1:
334
+ return
335
+
336
+ direction = self.momentum.last
337
+ normal = mesh.cell_normals[self.collision_cell_id]
338
+ adjacent = normal.dot(direction)
339
+ opposite = np.linalg.norm(np.cross(normal, direction))
340
+ tan_theta = opposite / adjacent
341
+ self.collision_angle = abs(math.atan(tan_theta))
342
+
343
+ def plot_trajectory(
344
+ self,
345
+ plotter: Plotter,
346
+ emission_color: str | None = None,
347
+ collision_color: str | None = None,
348
+ lw: int = 7,
349
+ r: int = 8,
350
+ **kwargs,
351
+ ) -> Any:
352
+ """Plot the trajectory of the particle in 3D.
353
+
354
+ Parameters
355
+ ----------
356
+ plotter :
357
+ Objet realizing the plots.
358
+ emission_color :
359
+ If provided, the first known position is colored with this color.
360
+ collision_color :
361
+ If provided, the last known position is colored with this color.
362
+ collision_point :
363
+ If provided and ``collision_color`` is not ``None``, we plot this
364
+ point instead of the last of ``points``. This is useful when the
365
+ extrapolated time is large, and actuel collision point may differ
366
+ significantly from last position points.
367
+ lw :
368
+ Trajectory line width.
369
+ r :
370
+ Size of the emission/collision points.
371
+
372
+ """
373
+ collision_point = self.collision_point
374
+ if collision_point.shape == (1, 3):
375
+ collision_point = collision_point[0]
376
+ return plotter.plot_trajectory(
377
+ points=self.position.to_list,
378
+ emission_color=emission_color if self.source_id != 0 else None,
379
+ collision_color=collision_color if not self.alive_at_end else None,
380
+ collision_point=collision_point,
381
+ lw=lw,
382
+ r=r,
383
+ **kwargs,
384
+ )
385
+
386
+
387
+ def _str_to_correct_types(line: PartMonLine) -> PartMonData:
388
+ """Convert the input line of strings to proper data types."""
389
+ corrected = (
390
+ float(line[0]),
391
+ float(line[1]),
392
+ float(line[2]),
393
+ float(line[3]),
394
+ float(line[4]),
395
+ float(line[5]),
396
+ float(line[6]),
397
+ float(line[7]),
398
+ float(line[8]),
399
+ float(line[9]),
400
+ int(line[10]),
401
+ int(line[11]),
402
+ )
403
+ return corrected
404
+
405
+
406
+ def _get_constant(variables: list[float]) -> float:
407
+ """Check that the list of floats is a constant, return constant."""
408
+ asarray = np.array(variables)
409
+ if not (asarray == asarray[0]).all():
410
+ raise ValueError
411
+ return asarray[0]
412
+
413
+
414
+ def _is_sorted(array: np.ndarray) -> bool:
415
+ """Check that given array is ordered (increasing values)."""
416
+ return (array == np.sort(array)).all()