PropagationSolver
PropagationSolver(
system=None,
t_min=0.0,
t_max=1.0,
t_steps=100,
method='mesolve',
opts=None,
savefile=None,
z_min=0.0,
z_max=1.0,
z_steps=10,
z_steps_inner=2,
num_density_z_func=None,
num_density_z_args=None,
interaction_strengths=None,
velocity_classes=None,
*,
atom=None,
)Solver for the propagation of fields through a medium of systems.
Steps the fields through space with a finite-difference method, solving the Lindblad master equation for the :class:~clerq.system.System at each step (once per velocity class if the medium is Doppler broadened).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| system | dict | None | Dict (or empty dict for defaults) describing the quantum system; passed to :class:~clerq.system.System. |
None |
| t_min | float | Start time of the simulation. | 0.0 |
| t_max | float | End time of the simulation. | 1.0 |
| t_steps | int | Number of time steps. | 100 |
| method | str | Solver method — 'mesolve' (Lindblad master equation) is the only supported value. |
'mesolve' |
| opts | dict | None | Dict of QuTiP solver options. | None |
| savefile | str | None | Path prefix for caching solved results ('.qu' extension appended automatically). Pass None to disable caching. |
None |
| z_min | float | The front of the medium. | 0.0 |
| z_max | float | The back of the medium. | 1.0 |
| z_steps | int | Number of space steps at which the solution is recorded. | 10 |
| z_steps_inner | int | Number of finite-difference steps made within each space step. | 2 |
| num_density_z_func | str | None | Name of a function in clerq.t_funcs giving the number density profile over z. Square by default. |
None |
| num_density_z_args | dict | None | Dict of arguments for num_density_z_func. |
None |
| interaction_strengths | list[float] | None | Interaction strength of each field with the medium, one for each field. | None |
| velocity_classes | dict | None | Dict defining the velocity classes for Doppler broadening, or None for no broadening. |
None |
| atom | dict | None | Deprecated name for system. |
None |
Methods
| Name | Description |
|---|---|
| build_velocity_classes | Build the velocity-class detuning grid and Boltzmann weights. |
| build_zlist | Builds the space grid. |
| check | Validates the PropagationSolver object. |
| coherences | Gets the sum of coherences (off-diagonals) in a list of coupled |
| coherences_field | Get the sum of coherences (off-diagonals) for the levels coupled by |
| fields_area | Gets the integrated pulse area of each field. |
| get_json_dict | Return the full problem definition as a JSON-serialisable dict. |
| init_Omegas_zt | Inits the Rabi frequency array. |
| init_states_zt | Inits the system density matrices. |
| load_results | Loads the solution from a QuTiP pickle file. |
| mbsolve | Deprecated name for :meth:PropagationSolver.solve. |
| mbsolve_ab | Deprecated; use :meth:PropagationSolver.solve with step="ab". |
| mbsolve_euler | Deprecated; use :meth:PropagationSolver.solve with step="euler". |
| populations | Gets the sum of populations in a list of levels. |
| populations_field | Gets the sum of populations for the upper (excited) level coupled by |
| save_results | Saves the solution to a QuTiP pickle file. |
| solve | Solves the propagation of the fields through the medium. |
| z_step | Returns the distance from one space point to the next. |
| z_step_inner | Returns the distance from one inner space point to the next. |
build_velocity_classes
PropagationSolver.build_velocity_classes(velocity_classes=None)Build the velocity-class detuning grid and Boltzmann weights.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| velocity_classes | dict | None | dict of velocity-class parameters, or None for the no-Doppler-broadening case (single detuning class at 0). | None |
Returns
| Name | Type | Description |
|---|---|---|
| tuple[np.ndarray, np.ndarray] | (thermal_delta_list, thermal_weights) |
build_zlist
PropagationSolver.build_zlist(z_min, z_max, z_steps, z_steps_inner)Builds the space grid.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| z_min | float | The front of the medium, in your chosen length unit. | required |
| z_max | float | The back of the medium. | required |
| z_steps | int | The number of even-spaced steps on which to solve and record the solution. | required |
| z_steps_inner | int | Between each z_step, make this many inner steps of the finite-difference solver (for numerical stability). | required |
Notes
- If the problem requires a lot of space steps for stability, but you don’t need to record the solution at such a high-level of resolution, increase z_steps_inner.
check
PropagationSolver.check()Validates the PropagationSolver object.
coherences
PropagationSolver.coherences(coupled_levels)Gets the sum of coherences (off-diagonals) in a list of coupled level pairs.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| coupled_levels | list[list[int]] | a list of pairs of level indexes | required |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.array, shape (z_steps+1, t_steps+1), dtype=complex |
Note
Unlike System.get_fields_sum_coherence, which operates on a single-z time series with per-field weighting factors, this method sums over the full (z, t) array with unit weights.
coherences_field
PropagationSolver.coherences_field(field_idx)Get the sum of coherences (off-diagonals) for the levels coupled by a field.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| field_idx | int | index in the list of fields | required |
Returns: np.array, shape (z_steps+1, t_steps+1), dtype=complex
fields_area
PropagationSolver.fields_area()Gets the integrated pulse area of each field.
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.array [num_fields, num_z_steps]: Integrated area of each field | |
| np.ndarray | over time |
get_json_dict
PropagationSolver.get_json_dict()Return the full problem definition as a JSON-serialisable dict.
init_Omegas_zt
PropagationSolver.init_Omegas_zt()Inits the Rabi frequency array.
Omegas_zt shape: (num_fields, z_steps+1, t_steps+1) — field-first. states_zt shape: (z_steps+1, t_steps+1, num_states, num_states) — z-first. These are inconsistent; correcting either is a breaking API change, deferred to a future major version.
init_states_zt
PropagationSolver.init_states_zt()Inits the system density matrices.
load_results
PropagationSolver.load_results()Loads the solution from a QuTiP pickle file.
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | if the savefile was built from a different problem definition (hash mismatch). |
Notes
- The path from which the results will be loaded is taken from self.savefile.
- Old savefiles without metadata are loaded without integrity checking, with a warning.
mbsolve
PropagationSolver.mbsolve(*args, **kwargs)Deprecated name for :meth:PropagationSolver.solve.
mbsolve_ab
PropagationSolver.mbsolve_ab(*args, **kwargs)Deprecated; use :meth:PropagationSolver.solve with step="ab".
mbsolve_euler
PropagationSolver.mbsolve_euler(*args, **kwargs)Deprecated; use :meth:PropagationSolver.solve with step="euler".
populations
PropagationSolver.populations(levels)Gets the sum of populations in a list of levels.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| levels | list[int] | a list of level indexes] | required |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.array, shape (z_steps+1, t_steps+1), dtype=np.real |
populations_field
PropagationSolver.populations_field(field_idx, upper=True)Gets the sum of populations for the upper (excited) level coupled by a field.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| field_idx | int | index in the list of fields | required |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.array, shape (z_steps+1, t_steps+1), dtype=np.real |
Note
- Casting upper to int so upper is 1, lower is 0.
save_results
PropagationSolver.save_results()Saves the solution to a QuTiP pickle file.
Notes
- The path to which the results will be saved is taken from self.savefile.
solve
PropagationSolver.solve(
step='ab',
rho0=None,
recalc=True,
progress=True,
progress_show_area=False,
check_counter_prop_depletion=True,
depletion_warn=0.01,
depletion_error=0.1,
)Solves the propagation of the fields through the medium.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| step | str | ‘euler (for Euler method) or ’ab’ (for Adams-Bashforth) | 'ab' |
| rho0 | Qobj | the initial density matrix state | None |
| recalc | bool | Recalculate the solution even if a savefile exists? | True |
| progress | bool | Show a tqdm progress bar with elapsed time, ETA and current max field amplitude. | True |
| progress_show_area | bool | Extend the progress bar with the pulse area ∫|Ω|dt for each field at the current z-step. Requires progress=True. | False |
| check_counter_prop_depletion | bool | Run a post-solve depletion check on any counter-propagating fields. Set False to suppress. | True |
| depletion_warn | float | Depletion fraction that triggers a UserWarning. | 0.01 |
| depletion_error | float | Depletion fraction that raises CounterPropagatingDepletionError. | 0.1 |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | self.Omegas_zt: The solved field complex Rabi frequency at each point in space z and time t. | |
| np.ndarray | self.states_zt: The solved density matrix at each point in space z and time t. |
z_step
PropagationSolver.z_step()Returns the distance from one space point to the next.
z_step_inner
PropagationSolver.z_step_inner()Returns the distance from one inner space point to the next.