**AtomicDensityMatrix** is a package for *Mathematica* 6 and later that facilitates analytic and numerical density-matrix calculations in atomic and related systems. It is intended to be both general and user-friendly, and to be useful to the working physicist as well as to students.

AtomicDensityMatrix is open source software, licensed under the GPLv3.

The package has been updated for compatibility with *Mathematica* 12. Please send bug reports to simon@rochesterscientific.com.

- Supports systems with an arbitrary number of states, automatically generating Zeeman and hyperfine substructure. Also supports calculations for model systems that neglect angular momentum
- Automatic generation of Hamiltonians including the effects of arbitrary static or dynamic electric, magnetic, and optical fields
- Routines for automatic application of the rotating-wave approximation
- Automatic generation of terms describing relaxation effects, including spontaneous decay
- Formulates and solves density matrix evolution equations, either analytically or numerically, as a function of time or in the steady state
- Routines implementing the matrix-continued fraction method for efficient numerical computation of periodic solutions for the case of modulated fields
- Supports generation and simultaneous solution of coupled density matrices describing different velocity classes and physical regions in the system
- Finds the effect of atomic polarization on light polarization, using various light polarization parameterization schemes
- Performs irreducible tensor decomposition of the density matrix
- General implementation of irreducible tensor algebra
- Performs arbitrary rotations of operators and irreducible tensors
- Automatic generation of level diagrams showing level structure, electromagnetic-field induced coupling, and atomic sublevel populations from the density matrix
- Plots angular-momentum probability surfaces: a 3D geometrical representation of atomic polarization
- An associated graphics package aids the generation of plots and animations for visualization of the physical processes
- A growing collection of basic and advanced examples, showing the application of the package to real atomic physics problems
- User extensible

Take a look at the online documentation for examples of what the package can do.

- Current version:
- Previous versions:
- ADM_18.09.08.zip (release notes)
- ADM_17.08.24.zip (release notes)
- ADM_17.06.12.zip (see release notes if upgrading to this version)
- ADM_17.05.31.zip (release notes)
- ADM_17.02.12.zip (see release notes if upgrading to this version)
- ADM_15.08.27.zip (release notes)
- ADM_15.04.24.zip (release notes)
- ADM_14.02.28.zip (release notes)
- ADM_13.07.19.zip (release notes)

First download ADM_yy.mm.dd.zip.

Installing a *Mathematica* package consists entirely of placing the package files in a location where *Mathematica* can find them. You can do this using one of the following two methods:

- Using the "File > Install" menu item (
*Mathematica*version 8 and up): - Start
*Mathematica*. - Select the menu item "File > Install".
- In the dialog box, for "Type of Item to Install" choose "Application" (
**not**"Package"; ADM is technically a*Mathematica*application, because it consists of a collection of packages). - For "Source" choose "From File..."
- When the file selector appears, choose the zip file that you have downloaded, and select "Open".
- Leave the "Install Name" as it's given, and click "OK".
*Mathematica*will extract the contents of the zip file and copy them to the correct install location.- Manually (all versions):
- Locate your
*Mathematica*base directory (for installation for all users) or user base directory (for installation for the current user only). You can find these directories by evaluating`$BaseDirectory`

or`$UserBaseDirectory`

in*Mathematica*. In*Mathematica*7 or later, you can open the directory in a file browser by evaluating

or`SystemOpen[$BaseDirectory]`

(Note that under Windows or Mac OS these directories may be hidden in the file system by default.)`SystemOpen[$UserBaseDirectory]`

- Unzip the contents of the downloaded zip archive into the "Applications" subdirectory of the base directory.
- The package files should now be in the directory

where`[BaseDirectory]/Applications/AtomicDensityMatrix`

`[BaseDirectory]`

is the directory you chose in the previous step.

To load and test the package in *Mathematica*, evaluate

`<<AtomicDensityMatrix``

and then

`$ADMVersion`

to see the package version number,

`AMPSPlot[DiagonalMatrix[{1, 0, 1}]]`

to see a simple angular-momentum-probability surface, and

`LevelDiagram[ZeemanSystem[1]]`

to plot the level diagram for a `J=1`

atomic system. There are many other examples in the documentation.

The package documentation is growing, but far from complete. It is available in the *Mathematica* Documentation Center when the package is installed. (You may have to restart *Mathematica* immediately after installation to see the AtomicDensityMatrix documentation appear in the Documentation Center.)

To view the documentation, select "Help > Documentation Center" (or press the F1 key), and click "Add-Ons and Packages" at the bottom of the page (for version 6, "Installed Add-Ons" on the bottom right). You will reach a page of links to the documentation for installed packages. Alternatively, you can just enter "adm" in the Documentation Center search bar—one of the first few results should be for the ADM package guide page. (This shortcut appears to be broken in *Mathematica* 10.1 only)

The documentation is also available online in html format.

The LGSBloch package is an extension to the Atomic Density Matrix package that contains routines for calculating the return flux from optically excited alkali atoms, specifically designed for Na atoms in the mesosphere.

The LGSBloch package requires *Mathematica* 7 or later.

To install, first install the ADM package. Then download LGSBloch_yy.mm.dd.zip below, and follow the same procedure as with the ADM package, so that the directory "LGSBloch" ends up in the "Applications" directory alongside the "AtomicDensityMatrix" directory.

Some basic documentation is available in the *Mathematica* Documentation Center after the package is installed. Press F1 to get the Documentation Center, and enter "LGSBloch" in the search box.

- Current version:
- LGSBloch_17.09.14.zip (Fixed to work with latest version of the ADM package. Also adds tutorials to the
*Mathematica*documentation center.)

- LGSBloch_17.09.14.zip (Fixed to work with latest version of the ADM package. Also adds tutorials to the
- Previous versions:
- LGSBloch_16.11.22.zip (Added option to view fluorescence at arbitrary angle.)
- LGSBloch_16.07.27.zip (Fixes to velocity-group selection routines that will improve accuracy. Removed dependence on deprecated VectorAnalysis package.)
- LGSBloch_15.04.27.zip (Changes to save function of StepPulseFlux.)
- LGSBloch_15.04.24.zip (Updated to work with latest version of ADM package, and separated LGSBlochUtilities into another package.)
- LGSBloch_12.06.25.zip (Added SimpleLGSBlochTest.nb file, and updated installation instructions.)
- LGSBloch_12.06.21.zip (Update to work with latest version of ADM package. Also, a bug with the handling of atomic recoil was fixed, which may cause small changes to return flux results. Other assorted improvements.)

- v20.04.27
- Refactored and updated
`MatrixRSolve`

.**Code using**`MatrixRSolve`

will need to be updated to use new syntax. - Allowed specification of
`PolarizationVector`

and`PropagationVector`

in spherical basis. - Updated and added documentation pages.
- Added
`AllowedCouplings`

option for`LevelDiagram`

. - Added
`DMSubstitute`

,`Submatrix`

,`TransitionEvaluate`

,`TransitionPosition`

,`PopulatedDM`

,`FluorescenceTensor`

functions. - Added
`Subspace`

option for`DensityMatrix`

. - Added new syntax for
`AllowedCouplings`

,`AllowedElements`

, and`NeglectedElements`

. - Fixed
`DiagonalMarixQ`

for*Mathematica*12. - Added
`NeglectedCouplings`

option for`WignerEckart`

.

- Refactored and updated
- v18.09.08
- Updated and added new documentation pages
- Made optimizations and bug fixes.
- Added
`TensorType`

,`TensorTypeQ`

,`TensorDepth`

functions. - Renamed
`MapOnComponents`

function as`ComponentMap`

. - Added
`AllowedCouplings`

and`NeglectedCouplings`

options for`Hamiltonian`

. - Added
`AllowedElements`

and`NeglectedElements`

options for`DensityMatrix`

. - Added additional atomic states and data for
`AtomicData`

. - Standardized behavior of
`WignerEckart`

for`Toy`

systems to match angular-momentum systems. - Changed
`Hamiltonian`

for`Toy`

systems to take the magnitude of the specified electric field if there is more than one Cartesian component. - Removed
`RotatingWaveTransform`

function; this functionality can be obtained with`RotatingWaveApproximation`

using the option`Method -> "KeepFastTerms"`

. - Refactored and generalized
`MatrixMultiply`

function, and added option`"MultiplyLevel"`

. - Renamed
`ContractOneByOnes`

option for`MatrixMultiply`

as`ScalarizeOneByOnes`

. - Added preliminary support for
`Fine`

and`Hyperfine`

atomic system types. - Expanded support for the polarization-moment basis for the density matrix.
- Added input checking and error messages for some functions.
- Defined
`Wedge`

and`Vee`

products as top and bottom level`MatrixMultiply`

operations, respectively.

- v17.08.24
- Added
`L`

and`S`

operators. `Hamiltonian`

now supports M1 transitions between fine-structure states.- New
`RestrictCoupling`

option for`Hamiltonian`

. - Optimized
`WignerEckart`

function for large systems. - Expanded functionality of
`Recomposition`

function. - New documentation pages for symbols.

- Added
- v17.06.12
- Added pressure broadening parameter to
`LinearAbsorption`

function and changed argument order.**Notebooks that use**`LinearAbsorption`

will need to be modified accordingly. - Updated "Linear Absorption Fitting" tutorial and added
`LinearAbsorption`

symbol page.

- Added pressure broadening parameter to
- v17.05.31
- Improvements to
`LevelDiagram`

. - Code refactoring.
- Allowed supplying an atomic system to
`ReducedME`

. - Symbol documentation pages for
`LevelDiagram`

,`AMPSPlot`

,`ToCartesian`

. - Bugfix for
`CartesianQ`

. - Generalized
`MatrixMultiply`

. - Removed
`MapOnParameters`

and`ReplaceMatrixElement`

functions. - Improved
`Energies`

and`TransitionFrequencies`

functions. - Added unit tests.
- Updated rotations tutorial.
- Removed
`SpontaneousEmission`

operator. - Set
`HyperfineShift`

to zero for Toy and Zeeman systems. - Fixed
`StateLabel`

so that undefined symbols can be used as labels. - Added Na 3D_3/2 state and Na branching ratios to
`AtomicData`

. - Added "Nonlinear Magneto-Optical Rotation in a Radio-Frequency field" tutorial.
- Changed default style options for
`Arrow3D`

. - Bugfix for
`TextOnTop`

function.

- Improvements to
- v17.02.12
- Updated for compatibility with
`Mathematica`

11. - Renamed
`Region`

to`ExperimentalRegion`

.**User notebooks that use**`Region`

will need to be updated. - Extended
`StateLabelQ`

and`StateMatchQ`

functions, removed deprecated syntax for`StatePosition`

and`StateMatchQ`

, added`StateEvaluate`

function. - Rewrote and improved
`LevelDiagram`

function. - Added
`Fluorescence`

function. - Fixed
`FluorescenceOperator`

for toy systems. - Set
`BranchingRatio`

to zero for same-parity states. - Added symbol documentation page for
`LevelDiagram`

. - Renamed
`GetLine`

to`GetLines`

. - Other minor fixes and improvements.

- Updated for compatibility with
- v15.08.27
- Moved
`Arrow3D`

and`PlotAndFit`

packages into the AtomicDensityMatrix application. These packages no longer have to be loaded separately. The Graphics and DataAnalysis folders have been removed from the ADM application.**When upgrading to this version, it is best to remove the old Graphics and DataAnalysis folders from the installation directory ($[User]BaseDirectory/Applications), to avoid accidentally loading old versions of these packages.** - Speed improvements in
`WignerEckart`

,`Hamiltonian`

, and`OpticalRepopulation`

. - Updates to
`Arrow3D`

for*Mathematica*10. Tweaked default graphics options for`Axes3D`

and`AMPSPlot`

. - Fixed options handling in
`PlotAndFit`

for*Mathematica*10. - Updated documentation for compatibility with
*Mathematica*10 graphics. - Added "Magneto-Optical Rotation in an Alkali Atom" tutorial.

- Moved
- v15.04.24
- Added GPL license info to source files.
- Removed dummy AtomicPhysics` package.
- For compatibility with
*Mathematica*10, renamed`Void`

as`VoidRegion`

.**User notebooks that use the**`Void`

command will need to be changed accordingly. - Adopted WWBCommon package for cross-version-compatible documentation.
- Higher-res banner and logo images.
- Speed improvements in
`FixTicks`

and`AlignedGraphicsGrid`

. - Reorganized and improved unit tests.

- v14.02.28
- Fixed behavior of
`BranchingRatio`

for setting branching ratios for inverse decays to zero. - Modified
`OpticalRepopulation`

to give more reasonable result when BranchingRatios are not specified. - Added rule to
`MatrixMultiply`

to allow multiplying a scalar operator by a (Cartesian) vector operator. - Changed possible values for
`Interaction`

option of`Hamiltonian`

to the strings`"Internal"`

,`"ElectricDipole"`

,`"MagneticDipole"`

, and`"Polarizability"`

- Updated (and renamed) the "Electromagnetically Induced Transparency and Atomic Polarization" example.
- Speed optimizations.
- Dummy position variables
`Xx`

,`Yy`

, and`Zz`

are defined only if the`VectorAnalysis``

package has not been loaded. If using`VectorAnalysis``

package, load it first to avoid name conflict warnings. - Modified
`OpticalField`

to produce simpler expressions for arbitrary polarization and propagation vectors. - Added and updated symbol documentation pages.

- Fixed behavior of
- v13.07.19
- Updated for compatibility with
*Mathematica*9:- In
*Mathematica*9, the functionality of`PhysicalConstants``

and`Units``

has been completely redesigned, and merged with the kernel. However, I don't think loading these packages causes any conflict with built-in functionality, so for backwards compatibility I'm going to continue loading these packages (and suppress the obsolete package warning). Please let me know if you encounter any conflicts. - The functionality of the
`VectorAnalysis``

package has been redesigned and incorporated into the kernel. There was very little use of it in the ADM package, so I was able to remove the dependency on the`VectorAnalysis``

package altogether. - There is a new
`TensorProduct`

function in*Mathematica*9, so the ADM`TensorProduct`

function has been renamed`SphericalTensorProduct`

- Renamed
`Label`

as`StateLabel`

; the option`Label`

for`DensityMatrix`

has been renamed`DMLabel`

.**User notebooks that use the**`Label`

command will need to be changed correspondingly. - Fixed problems stemming from new (fixed)
`ComplexExpand`

behavior. - Native documentation was restyled in version 9, producing some ugly layout problems in the ADM documentation. Cross-version documentation has now been implemented using the method described here.

- In
- Updated documentation.
- Fixed a bug blocking the package from showing up in the "Add-ons" section of the Documentation Center.
- Fixed web links in the ADM documentation, making them point to the online version of the documentation.
- Made functions for obtaining atomic parameters automatically thread over atomic systems.
- Speed optimizations.
- Changed optical field parameterization specifications to strings.

- Updated for compatibility with
- v13.07.07
- Added "Nonlinear Magneto-optical Rotation with Frequency-modulated Light" example.
- Updated "EIT and Atomic Polarization", "Breit-Rabi", "Rotating-wave Approximation", and other assorted tutorials.
- Added symbol pages for
`RotatingWaveApproximation`

and`F`

. - Modified
`DropFastTerms`

(and`RotatingWaveApproximation`

) so that sums of two different optical frequencies are not dropped. Also extended to allow some more complicated expressions as frequency arguments. - Extended
`StatePosition`

,`SelectStates`

, and related functions to allow specification of the selection criteria`Label ==`

*lab*as just*lab*. - Extended
`RotatingWaveApproximation`

,`RotatingWaveTransform`

and`RotatingWaveTransformMatrix`

to automatically generate the RWA transform matrix given a list of optical frequencies and the associated levels that they couple. Also allow the possibility to specify the optical detuning parameters along with the optical frequencies. - Defined new function
`ReplaceMatrixElement`

that applies replacement rules to particular matrix elements in an operator selected according to their corresponding`AtomicState`

parameters. - Defined new function
`StateMatchQ`

- v13.06.09
- Corrected the units for quantities in AtomicData by changing
`Hertz`

to`1/Second`

(all quantities are in omega units, rad/sec, but were incorrectly labelled as being Hertz).**If your application depends on the AtomicData package, it may require modification.** - Extended
`RotatingWaveTransformMatrix`

to allow manual specification of level shifts - Changed
`ToContravariant`

and`ToCovariant`

to use`Dual`

rather than`GeneralizedConjugateTranspose`

when converting between co- and contravariant quantities in order to correctly handle complex vectors - Included
`SphericalPhase`

parameterization in`OpticalField`

- Modified
`BranchingRatio`

so that it returns zero if it can tell that the reverse branching ratio is nonzero. - Fixed links in documentation.
- Updated documentation.
- Updated installation instructions

- Corrected the units for quantities in AtomicData by changing
- v12.08.15
- Added parities for alkali states to
`AtomicData`

- Added
`ParityOffset`

option to`LevelDiagram`

- Updated and added usage messages.

- Added parities for alkali states to
- v12.06.21
- Documented the Voigt profile in the "Linear Absorption Fitting" example
- Modified
`SublevelMultiplicity`

so that it returns`(2F+1)`

when`F`

is defined (suggested by Guobin Liu) - Modified
`DopplerWidth`

to work if lower and upper states are given in either order (suggested by Guobin Liu) `WignerD`

is defined as a system function in*Mathematica*8. Therefore the ADM version of`WignerD`

has been renamed`ADMWignerD`

, and the built-in`WignerD`

has been overloaded so that it calls`ADMWignerD`

when given arguments that match the`ADMWignerD`

format.- Fixed linear absorption for Toy systems
`SelectStates`

now allows boolean operators in the selection criteria- Speed enhancements
- Split more functions into subpackages
- Removed outer matrix in return value of
`PolarizationMatrices`

with numerical argument `LevelDiagram`

improvements- Assorted documentation improvements

- v10.07.17
- Package now loads with
`<<AtomicDensityMatrix``

rather than`<<AtomicPhysics``

. A dummy`AtomicPhysics`

package that calls the`AtomicDensityMatrix`

package is provided for backwards compatibility. - Updated documentation

- Package now loads with
- v10.07.09
- Standardized
`WignerRotate`

function - Standardized
`AMPSPlot`

for polarization-moment expansions - Added "Quantum-mechanical rotations" tutorial
- Updated documentation

- Standardized
- v10.06.28
- Added options to
`Ket`

function - Updated some tutorials
- Split
`LevelDiagram`

and perturbative solve functions into subpackages - Fixed bug in
`LevelDiagram`

for*Mathematica*6.0 and made speed improvements

- Added options to
- v10.04.28
- Speed improvements in
`SteadyStatePerturbativeSolve`

,`OpticalRepopulation`

- Speed improvements in
- v10.04.20
- Modified package context structure
- Speed optimizations
- Migrated development to Wolfram Workbench
- Added
`DopplerWidth`

and`MostProbableSpeed`

functions - Added "Linear Absorption Fitting" example
- Fixed
`Component`

function for tensor decomposition matrix input - Combined
`DMElementPattern`

and`DMElementPartPattern`

functions

- v09.12.08
- Corrected sign error in optical-field azimuthal angle
- Flipped rotating wave transform from active to passive
- Changed
`UnitaryTransformation`

to`EffectiveHamiltonian`

- Changed
`DMRotating`

to`DMFromRotatingDM`

- Included
`PlotAndFit`

package in distribution

- v09.09.07
- Added potassium to
`AtomicData`

- Added
`AtomicTransition`

function to`AtomicData`

package

- Added potassium to
- v09.08.07
- Added
`ExcitedStates`

function - Added
`LinearAbsorption`

function - Improved
`LevelDiagram`

function - Improved
`SphericalTensorQ`

function - Extended
`SublevelMultiplicity`

function - Change in internals of
`WignerEckart`

function - Fixed bug in
`RotatingWaveTransform`

- Added
- v09.06.09
- Internal change in
`ExprToReIm`

- Fixed bug in
`DMElementPattern`

- Fixed bug in
`FluorescenceOperator`

for angle-integrated case

- Internal change in
- v08.12.09
- Improved
`LevelDiagram`

function - Renamed
`FluorescenceOperator`

as`OpticalRepopulationOperator`

, added new`FluorescenceOperator`

function that calculates fluorescence into a solid angle - Wrote usage messages for some symbols.
- Updated values in
`AtomicData`

and added Na

- Improved
- v08.10.30
- Improved
`TensorForm`

,`Component`

,`PolarizationMoments`

,`LevelDiagram`

functions - Added
`PolarizationMoments`

representation to`OpticalRepopulation`

function - Set up
`LiouvilleEquation`

function to produce Bloch equations in terms of polarization moments - Extended
`ToCartesian`

function to apply to operators and arbitrary rank spherical tensors - Added "EIT and Atomic Polarization" example

- Improved
- v08.10.23
- Worked on
`LevelDiagram`

function - Separated out
`AtomicDensityMatrix`Common``

package - Changed behavior of
`F`

parameter: it now returns`J`

if`F`

is not defined - Changed labeling of density matrix elements in Toy systems: labels are no longer enclosed in lists
- Generalized tensor operations to include imaginary/nonhermitian tensors
- Improved
`TensorForm`

function - Updated "MatrixNotation", "Matrix Multiplication" tutorials

- Worked on
- v08.10.07
- Fixed bug in
`Recomposition`

function - Improved
`LevelDiagram`

function - Updated "Angular-momentum Probability surfaces" example
- Improved "Collapse and Revival Quantum Beats" example

- Fixed bug in
- v08.09.22
- Expanded "Two-level system", and "NMOR" examples
- Updated "Breit-Rabi Diagram", "Collapse and Revival", "Three-level System", "Angular-momentum Probability Surfaces" examples
- Improved
`LevelDiagram`

,`TransitRepopulation`

,`DensityMatrix`

,`DMVariables`

,`Recomposition`

functions - Changed polarization moment expansion coefficients to contravariant to match Varshalovich
- Fixed bug in
`Component`

function - Added
`CovariantDecompositionQ`

,`ContravariantDecompositionQ`

,`CovariantDecompositionMatrixQ`

,`ContravariantDecompositionMatrixQ`

,`TensorForm`

functions - Added link to source code in documentation

- v08.07.07
- Added "The AC Stark Effect" example
- Added "The Wigner-Eckart Theorem", "Constructing the Hamiltonian", "The Rotating-wave Approximation" tutorials
- Improved
`LevelDiagram`

function

- v08.06.29
- Got documentation working in 6.0.3
- Revamped Guide page
- Added "Displaying the Density Matrix" tutorial
- Added "Collapse and Revival Quantum Beats" example
- Added symbol reference pages for
`DensityMatrix`

,`DMVariables`

,`Ket`

,`AtomicState`

,`L`

,`S`

- Added
`$ADMVersion`

symbol.

- v08.05.26
- Streamlined internals of
`OpticalField`

- Improved
`Region`

input to`Hamiltonian`

- Eliminated
`FractionalDensity`

Region parameter - Included case of multiple ground states in
`TransitRepopulation`

- Added "Isolating the Hexadecapole Moment" example
- Added
`GFactor`

parameter to`AtomicState`

- Added
`LevelDiagram`

function (prototype) - Added "The Stark Effect" example
- Added "Hyperfine Structure: Breit-Rabi Diagram" example

- Streamlined internals of

Please send questions, suggestions, and bug reports to Simon Rochester at simon@rochesterscientific.com.