rotsim2d.pathways#

Generate all Liouville pathways for nth order rovibrational excitation.

Enums#

`Side`(value)	Ket- or Bra-side excitation by `LightInteraction`
`KSign`(value)	Positive or negative part light spectrum.

LightInteraction(name, side, sign[, ...])

Represents (dipole) interaction between the system and a light beam.

`LightInteraction.name`	Identifier for the light beam.
`LightInteraction.side`	Ket or bra excitation.
`LightInteraction.sign`	Wavevector sign of created polarization contribution.
`LightInteraction.angle`	Single float for linear polarization and pair of numbers for elliptical.
`LightInteraction.readout`	Readout or actual light interaction.
`LightInteraction.tier`	Number of interactions preceding this one in the tree.

`LightInteraction.is_absorption`()	True if absorption within dipole approximation.
`LightInteraction.evolve`(**kwargs)	Return copy with some attributes replaced.
`LightInteraction.conj`()	Return detached conjugate of this LightInteraction.

KetBra(ket, bra[, parent, children])

Node in a tree of excited states.

`KetBra.ket`	ket-side rovibrational state
`KetBra.bra`	bra-side rovibrational state
`KetBra.name`	ASCII art KetBra

These methods are primarily useful for leaf nodes.

`KetBra.is_diagonal`()	Check if current node is a population state.
`KetBra.is_rephasing`()	Check if current pathway is rephasing.
`KetBra.is_SI`([order])	Check if \(\vec{k}_s = -\vec{k}_1+\vec{k}_2+\vec{k}_3\) (rephasing).
`KetBra.is_SII`([order])	Check if \(\vec{k}_s=\vec{k}_1-\vec{k}_2+\vec{k}_3\) (non-rephasing).
`KetBra.is_SIII`([order])	Check if \(\vec{k}_s=\vec{k}_1+\vec{k}_2-\vec{k}_3\) (double quantum).
`KetBra.is_Pinitial`()	Check if initial excitation is P-branch.
`KetBra.is_Rinitial`()	Check if initial excitation is R-branch.
`KetBra.is_Qinitial`()	Check if initial excitation is Q-branch.
`KetBra.is_Qbranch`()	Check if pump or probe axis involves Q-branch coherence.
`KetBra.is_esa`()	Check if pathway corresponds to excited-state absorption.
`KetBra.is_sep`()	Check if pathway corresponds to stimulated emission pumping.
`KetBra.is_gshb`()	Check if pathway corresponds to ground-state hole-burning.
`KetBra.is_doublequantum`()	Check if pathway has double-quantum coherence.
`KetBra.is_interstate`()	Check for coherent state after second interaction.
`KetBra.is_dfwm`()	Check if this pathway contains only coherences corresponding to a single dipole transition.
`KetBra.is_twocolor`()	Check if pathway is two-color.
`KetBra.is_threecolor`()	Check if pathway is three-color.

`KetBra.is_between`(pump, probe)	Check if this pathway produces cross-peak between `pump` and `probe`.
`KetBra.is_same_branch`(o)	Check if other pathway belongs to the same branch.
`KetBra.is_equiv_pathway`(o)	Check if other pathway differs only by initial J state.
`KetBra.is_pathway`(*kbs)	Match self to pathway consisting of kbs.
`KetBra.is_some_pathway`(kbs)	Match self to one of pathways in kbs.

`KetBra.copy`()	Deep copy of the tree.
`KetBra.evolve`(**kwargs)	Return copy with some attributes replaced.
`KetBra.get`(side)	Index KetBra by Side enum.
`KetBra.conj`()	Return detached conjugate of this KetBra.
`KetBra.savepng`(path)	Save excitation tree as an image.
`KetBra.normalized`()	Return copy of self with ket being the lower nu, j level.
`KetBra.print_tree`()	Pretty print excitation tree.
`KetBra.kb_ancestor`([ancestor])	Return first KetBra ancestor.
`KetBra.diagonals`([sort])	Collect diagonal leaves.
`KetBra.ketbras`()	Ancestor KetBras and self, from top to bottom.
`KetBra.interactions`()	Interactions which generated this KetBra, from top to bottom.
`KetBra.interaction`(name)	Return `LightInteraction` with given name.
`KetBra.ksigns`()	Return signs of wavevectors of interactions.
`KetBra.total_ksign`()	Cumulative sign of the term.
`KetBra.sides`()	Return sides of DM on which interactions acted.
`KetBra.total_side`()	Cumulative side of the term.
`KetBra.transitions`()	Return list of transitions as a list of state pairs.
`KetBra.color_tier`()	Number of colors neede to create this pathway.
`KetBra.to_statelist`([diatom, normalize])	KetBras leading to this one as a list of state pairs.

`only_between`(ketbra, pump, probe)	Limit tree to pathways between `pump` and `probe`.
`only_pathway`(ketbra, pathway)	Retain only `pathway` in excitation tree.
`only_some_pathway`(ketbra, pathways)	Retain only pathways in `pathways`.
`make_remove`(func)	Remove all pathways for which `func` is True.
`make_only`(func)	Retain only pathways for which `func` is True.

The tree-filtering functions below were generated with make_only() and make_remove(). Their names should be self-explanatory. For example:

only_SI = make_only(lambda kb: kb.is_SI())

`prune`(ketbra, depth)	Remove leaves whose depth is less than `depth`.
`readout`(ketbra)	Retain only dipole-allowed pathways.
`flip_readout`(ketbra)	Flip the side of readout.
`copy_chain`(ketbra)	Make a single-child tree ending with `ketbra` leaf.
`conjugate_chain`(ketbra)	Return excitation chain with all nodes conjugated.
`zannify_chain`(ketbra)	Conjugate SI pathways, ensure that readout is emissive.
`zannify_tree`(ketbra)	Ensure that readout in the whole tree is emissive.
`excited_states_symtop`(state, dnu)	Return symtop states reachable from `state` by dipole interaction.
`excited_states_diatom`(state, dnu)	Return diatom states reachable from `state` by dipole interaction.
`excite`(ketbra, light_name[, part, readout])	Generate all excitations of `ketbra`.
`multi_excite`(ketbra, light_names[, parts])	Generate multiple excitations of `ketbra`.
`gen_roots`(jiter[, rotor, kiter_func])	Return a list of `KetBra` in ground vibrational state.
`gen_excitations`(root, light_names, parts[, ...])	Generate excitation tree, filter it and retain only resonant pathways.
`gen_pathways`(jiter[, meths, rotor, ...])	Generate multiple excitation trees, filter them and retain resonant ones.
`geometric_factor`(leaf)	Return polarization and angular momentum sequence for a pathway.