gcmotion.events#
Events are used by SciPy’s solve_ivp solver to locate where certain
conditions are met during the solving, and optionally terminate the solving
after a certain amount of times those conditions are found. More info here.
Events are function handles of analytical funtions, and they trigger when
their return expression is equal to 0. Since solve_ivp uses a root find
algorithm to locate the exact position of the event, the expressions must be 0
and change sings around the root.
We can use multiple events, and the solver will return a list with the triggered positions for each of them.
Examples#
To use an event in a particle, you must pass it to its
run() method as such:
events = [gcm.events.when_theta(theta0, 8)]
particle.run(events=events)
This event will stop the solver after \(\theta\) was taken its initial value 8 times, regardless if the particle turns out to be passing or trapped. Note that this does not mean 8 periods, since the motion is multi- periodic.
Available Events#
when_theta |
|
when_psi |
|
when_zeta |
|
when_rho |
Defines the event constructor, which creates SciPy-ready event functions. Note that since the solver only solves for “theta”, “psi”, “zeta” and “rho”, these are the only ones that can be tracked. The Canonical momenta and psip are calculated afterwards.
- gcmotion.events.when_theta(root, terminal: int = 0, direction: float = 0)#
Occurs at \(\theta\) =
root.- Parameters:
- root: int | Quantity
The \(\theta\) value to be tracked.
- terminal: int, optional
After how many occurences to terminate the solver. As SciPy defines it:
terminal=0: Do not terminate the solver (still tracks occurences).
terminal>=1: Stop the solver after “terminal” occurences
Defaults to 0.
- direction: float, optional
Direction of a zero crossing. If direction is positive, event will only trigger when going from negative to positive, and vice versa if direction is negative. If 0, then either direction will trigger event. Implicitly 0 if not assigned. Note that this is not necessarily the direction of zero crossing of the variable itself, but the event’s analytical expression. Defaults to 0.
- gcmotion.events.when_psi(root, terminal: int = 0, direction: float = 0)#
Occurs at \(\psi\) =
root.- Parameters:
- root: int | Quantity
The \(\psi\) value to be tracked.
- terminal: int, optional
After how many occurences to terminate the solver. As SciPy defines it:
terminal=0: Do not terminate the solver (still tracks occurences).
terminal>=1: Stop the solver after “terminal” occurences
Defaults to 0.
- direction: float, optional
Direction of a zero crossing. If direction is positive, event will only trigger when going from negative to positive, and vice versa if direction is negative. If 0, then either direction will trigger event. Implicitly 0 if not assigned. Note that this is not necessarily the direction of zero crossing of the variable itself, but the event’s analytical expression. Defaults to 0.
- gcmotion.events.when_zeta(root, terminal: int = 0, direction: float = 0)#
Occurs at \(\zeta\) =
root.- Parameters:
- root: int | Quantity
The \(\zeta\) value to be tracked.
- terminal: int, optional
After how many occurences to terminate the solver. As SciPy defines it:
terminal=0: Do not terminate the solver (still tracks occurences).
terminal>=1: Stop the solver after “terminal” occurences
Defaults to 0.
- direction: float, optional
Direction of a zero crossing. If direction is positive, event will only trigger when going from negative to positive, and vice versa if direction is negative. If 0, then either direction will trigger event. Implicitly 0 if not assigned. Note that this is not necessarily the direction of zero crossing of the variable itself, but the event’s analytical expression. Defaults to 0.
- gcmotion.events.when_rho(root, terminal: int = 0, direction: float = 0)#
Occurs at \(\rho_{||}\) =
root.- Parameters:
- root: int | Quantity
The \(\rho_{||}\) value to be tracked.
- terminal: int, optional
After how many occurences to terminate the solver. As SciPy defines it:
terminal=0: Do not terminate the solver (still tracks occurences).
terminal>=1: Stop the solver after “terminal” occurences
Defaults to 0.
- direction: float, optional
Direction of a zero crossing. If direction is positive, event will only trigger when going from negative to positive, and vice versa if direction is negative. If 0, then either direction will trigger event. Implicitly 0 if not assigned. Note that this is not necessarily the direction of zero crossing of the variable itself, but the event’s analytical expression. Defaults to 0.