      /**
     @mainpage Dipelm: A code to calculate photoionization observables
    
     [TOC]
    
     @section Introduction

     Dipelm calculates:

     - Photoionization cross sections and asymmetry paramters for randomly oriented molecules.
     - Molecular frame photoionization dipoles (MFDip) and photoelectron angular distributions (MFPAD).
     - Lab frame photoionization dipoles (LFDip) and photoelectron angular distributions (LFPAD). 
     
     @section input Input
     
     @subsection input1 File input
     
     Dipelm takes partial wave transition moments produced by rsolve (in the routine comppwd) as input
     
     @subsection input2 Namelist input
     
     Dipelm has one required namelist, @ref DIPELMINP "&dipelminp", and two optional namelists @ref SMOOTH "&smooth" and @ref ORIENT "&orient".
     
     \b &dipelminp controls input file data. 
     One can also select a subset of states for randomly oriented molecule observables
     (default behaviour is to use all states).

     \b &smooth controls smoothing of the partial wave dipoles prior to calculation of observables.
     This can be useful if one wants to remove narrow unphysical pseudoresonances (narrow real resonances
     will also be removed).
     For dense energy grids and many partial wave channels this can take sometime.
     Only the subset of states chosen in &dipelminp will be smoothed.

     \b &orient controls calculation of oriented observables. Default behaviour is to calculate the molecular frame
     photoionization dipoles and angular distributions, which are resolved in initial and final state, photon energy, and
     photoelectron direction. Only the MFPAD are output unless otherwise requested.
     Optionally, lab frame dipoles and angular distributions for a range of orientations will be calculated.
     File sizes can quickly become very large with this last option,  so some restraint with the angular grids 
     (alpha, beta, gamma, theta, phi) must be shown.
     
     @ref DIPELMINP "[&dipelminp", @ref SMOOTH "&smooth", @ref ORIENT "&orient]"

     @section output Output
     
     All output files containing observables are prepended with photo_
     
     @subsection output1 Randomly oriented molecules
     
     By default the output files generated are:
     
     - photo_total_xsec: Total photoionization cross section for all neutral states. 
     - photo_xsec: Partial photoionization cross sections for all pairs of ion and neutral states
     - photo_beta_1c: Dichroic parameter (circular polarization) for all pairs of ion and neutral states
     - photo_beta_2l: Asymmetry parameter (linear polarization) for all pairs of ion and neutral states
     - photo_beta_2c: Asymmetry parameter (circular polarization) for all pairs of ion and neutral states
 
     The first column is the photon energy (eV), following columns correspond to the observable in 
     question for each ion state (in energy order by default) for ion state resolved observables. 
     Each neutral state starts a new block, again in energy order.
     
     Optionally, each state pair can be output to a seperate file, in this case the file names above
     are appended with _ion_state_i_neutral_state_j, where i and j index the ion and neutral states
     respectively (in energy order by default). Each file then consists of two columns, the photon energy and
     the observable. photo_total_xsec is appended with only _neutral_state_j.
     
     @subsection output2 Oriented molecules
          
     If oriented observables are calculated,  the output files generated are:
     
     - photo_MFPAD_ion_state_i_neutral_state_j: The MFPAD (default)
     - photo_MFDip_ion_state_i_neutral_state_j: The MFDip (optional)
     - photo_LFPAD_ion_state_i_neutral_state_j: The LFPAD (optional)
     - photo_LFDip_ion_state_i_neutral_state_j: The LFDip (optional)

     Photon energies
     Currently the y, z, and x cartesian components of the dipoles are output in the dipoles files (in that order).
     These correspond to y, z and x linearly polarized light directions in the PAD files.
     Circular polarization is not currently implemented (but will be in a future release).
     If it is required it can be obtained by post-processing of the dipole files to transform the cartesian
     components to the spherical basis, then taking the modulus squared and multiplying by the photon
     energy dependent coefficient (see dipole_procs::calculate_MFPAD). Photon energy is in Hartree, in 
     contrast to randomly oriented molecule observables.

     The files are in binary stream format, to read and plot them see the following:
            
     [Python read and plot example](python_read.html)

     */
