%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% --------------------------------------------------------------------------- %
% - MOdiagram - modiagram_doc_en.tex                                        - %
% - easy creation of molecular orbital diagrams                             - %
% --------------------------------------------------------------------------- %
% - Clemens NIEDERBERGER                                                    - %
% - 2011/09/25                                                              - %
% --------------------------------------------------------------------------- %
% - http://www.mychemistry.eu/                                              - %
% - contact@mychemistry.eu                                                  - %
% --------------------------------------------------------------------------- %
% - If you have any ideas, questions, suggestions or bugs to report, please - %
% - feel free to contact me.                                                - %
% --------------------------------------------------------------------------- %
% - Copyright 2011 Clemens Niederberger                                     - %
% -                                                                         - %
% - This work may be distributed and/or modified under the                  - %
% - conditions of the LaTeX Project Public License, either version 1.3      - %
% - of this license or (at your option) any later version.                  - %
% - The latest version of this license is in                                - %
% -   http://www.latex-project.org/lppl.txt                                 - %
% - and version 1.3 or later is part of all distributions of LaTeX          - %
% - version 2005/12/01 or later.                                            - %
% -                                                                         - %
% - This work has the LPPL maintenance status `maintained'.                 - %
% -                                                                         - %
% - The Current Maintainer of this work is Clemens Niederberger.            - %
% -                                                                         - %
% - This work consists of the files modiagram.sty, modiagram_doc_de.tex,    - %
% - modiagram_doc_de.tex, README                                            - %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass{scrartcl}
\usepackage{xparse}[2011/09/05]
\usepackage[english]{babel}
\usepackage[utf8]{inputenx}
\usepackage[dvipsnames]{xcolor}
  \colorlet{code}{RawSienna}
\usepackage{modiagram,xspace,siunitx,framed,chemfig}
\usepackage{showexpl}
\usepackage[version=3]{mhchem}

\usepackage{showexpl}
\lstset{
  language         = [LaTeX]TeX,
  basicstyle       = {\ttfamily\small\color{code!80}},
  breaklines       = true,
  commentstyle     = {\color[named]{Gray}},
  backgroundcolor  = \color{yellow!20},
  numbers          = left,
  numberstyle      = \tiny,
  numberblanklines = true,
  numbersep        = .3em,
  xleftmargin      = 1em,
  gobble           = 1
}

\usepackage{hyperref}
\hypersetup
  {
    colorlinks         = true,
    urlcolor           = blue!80,
    linkcolor          = blue!80,
    plainpages         = false,
    bookmarksopen      = true,
    bookmarksopenlevel = 2,
    bookmarksnumbered  = true,
    pdfauthor          = {Clemens Niederberger},
    pdftitle           = {MOdiagram - Manual},
    pdfsubject         = {Create MO diagrams with LaTeX},
    pdfkeywords        = {MOdiagram},
    pdfcreator         = {LaTeX}
  }

\newcommand*\MOname{\textsf{MOdiagram}\xspace}
\newcommand*\MOversion{0.1\xspace}
\newcommand*\MOdate{2011/09/25}

\newcommand*\paket[1]{\textsf{#1}\footnote{\url{http://www.ctan.org/pkg/#1/}}}
% \newcommand*\paket[1]{\textsf{#1}}

\newcommand*\changefont[3]{\fontfamily{#1}\fontseries{#2}\fontshape{#3}\selectfont}

\DeclareDocumentEnvironment{myquote}{o}
  {\quote\small\changefont{cmss}{m}{sl}}
  {\IfNoValueF{#1}{\par\noindent\parbox{\linewidth}{\raggedleft\normalfont\itshape#1}}\endquote}
\NewDocumentCommand\cmd{v}{{\color{code!80}\ttfamily#1}}

\newcommand*\TikZ{\mbox{Ti\textbf{\textit{k}}Z}\xspace}
\newcommand*\bzw{\mbox{bzw.}\xspace}

\begin{document}

\begin{titlepage}
 \centering
 \Huge MOdiagram v\MOversion
 \vskip.5cm
 \Large\MOdate
 \vskip.5cm
 \large Clemens \textsc{Niederberger}
 \vskip.25cm
 \normalsize\url{http://www.mychemistry.eu/}\\
 \href{mailto:contact@mychemistry.eu}{contact@mychemistry.eu}
 \vskip2cm
 \begin{abstract}
  \MOname provides an environment and commands for the creation of molecular orbital diagrams.
 \end{abstract}
 \begin{MOdiagram}[style=fancy,distance=7cm,AO-width=15pt,labels,names]
  \atom[N]{left}{
    2p = {0;up,up,up}
  }
  \atom[O]{right}{
    2p = {2;pair,up,up}
  }
  \molecule[NO]{
    2pMO = {1.8,.4;pair,pair,pair,up,,},
    color = { 2piy*=red }
  }
 \end{MOdiagram}
\end{titlepage}

\tableofcontents

\section{Licence, Requirements}
\MOname v\MOversion underlies the \LaTeX\ Project Public License version 1.3 or later.\newline(\url{http://www.latex-project.org/lppl.txt})

\MOname needs the packages \paket{expl3}, \paket{xparse}, \paket{l3keys2e}, \textsf{tikz}\footnote{\url{http://www.ctan.org/pkg/pgf/}}, \paket{amsmath} and \paket{textgreek}. Additionally the \TikZ libraries \textsf{calc} and \textsf{arrows} are loaded.

It is useful to be familiar with the \paket{pgf} or the \paket{tikz} package.

\section{Motivation}
This package has been written as a reaction to a question on \url{http://tex.stackexchange.com/}. To be more precise: as a rection to the question \href{http://tex.stackexchange.com/questions/13863/molecular-orbital-diagrams-in-latex}{Molecular orbital diagrams in LaTeX}. There it says
\begin{myquote}
 I'm wondering if anyone has seen a package for drawing (qualitative) molecular orbital splitting diagrams in \LaTeX? Or if there exist any packages that can be easily re-purposed to this task?

 Otherwise, I think I'll have a go at it in \TikZ.
\end{myquote}
The problem was solved using \TikZ, since no package existed for that purpose. \MOname is intended to fill this gap.

\section{Main Commands}
Every molecular orbital (MO) diagrams are created using the environment \cmd=MOdiagram= . Inside this environment two commands are important to begin with.

\subsection{The \texttt{\textbackslash atom} Command}
\begin{framed}
 \cmd=\atom[<name>]{<pos>}{<AO-spec>}=
 \begin{itemize}\small
  \item\cmd=<name>= (o) caption of the atom
  \item\cmd=<pos>= (m) on the left or the right in the diagram
  \item\cmd=<AO-spec>= (m) specifications of the atomic orbitals (AO)
 \end{itemize}
\end{framed}
Let's take a look at an example:

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{right}{
    1s = {  0; pair} ,
    2s = {  1; pair} ,
    2p = {1.5; up, down, }
  }
 \end{MOdiagram}
\end{LTXexample}

As you can see, the argument \cmd=<AO-spec>= is essential to create the actual orbitals and the electrons within. You can use these key/value pairs to specify what you need:
\begin{framed}
 \begin{itemize}
  \item\cmd+1s={<rel. energy>; <el-spec>}+
  \item\cmd+2s={<rel. energy>; <el-spec>}+
  \item\cmd+2p={<rel. energy>; <x el-spec>, <y el-spec>, <z el-spec>}+
 \end{itemize}
\end{framed}
\cmd=<el-spec>= can have the values \cmd=pair=, \cmd=up= and \cmd=down= or can be left empty. \cmd=<rel. energy>= actually is the $y$ coordinate ansd shifts the AO vertically by \cmd=<rel. energy>= \si{\centi\metre}.

The argument \cmd=<pos>= is important, when p orbitals are used. For instance compare the following example to the one before:

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left}{
    1s = {  0; pair} ,
    2s = {  1; pair} ,
    2p = {1.5; up, down, }
  }
 \end{MOdiagram}
\end{LTXexample}


When both variants are used one can also see, that the right atom is shifted to the right (hence the naming). The right atom is shifted by \SI{4}{\centi\metre} per default and canbe adjusted individually, see page \pageref{option:distance}.

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left}{
    1s = {  0; pair} ,
    2s = {  1; pair} ,
    2p = {1.5; up, down, }
  }
  \atom{right}{
    1s = {  0; pair} ,
    2s = {  1; pair} ,
    2p = {1.5; up, down, }
  }
 \end{MOdiagram}
\end{LTXexample}

With the next command the reason for the shift becomes clear.

\subsection{The \texttt{\textbackslash molecule} command}
\begin{framed}
 \cmd=\molecule[<name>]{<MO-spec>}=
 \begin{itemize}\small
  \item\cmd=<name>= (o) caption of the molekule
  \item\cmd=<MO-spec>= (m) specifications of the molecular orbitals (MO)
 \end{itemize}
\end{framed}
An example first:

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left} { 1s = {  0; up} }
  \atom{right}{ 1s = {  0; up} }
  \molecule { 1sMO = {.75; pair, } }
 \end{MOdiagram}
\end{LTXexample}

The command \cmd=\molecule= connects the AO with the bonding and anti-bondung MO. \cmd=\molecule= can only be used \emph{after} one has set \emph{both} atoms, since the orbitals, that should be connected, must be known.

The argument \cmd=<MO-spec>= accepts a comma separated list of key/value pairs:
\begin{framed}
 \begin{itemize}
  \item\cmd+1sMO={<energy gain>; <s el-spec>, <s* el-spec>}+ (connects the AO specified by \cmd=1s=)
  \item\cmd+2sMO={<energy gain>; <s el-spec>, <s* el-spec>}+ (connects the AO specified by \cmd=2s=)
  \item\cmd+2pMO={<s energy gain>, <p energy gain>; <s el-spec>, <py el-spec>, <pz el- spec>, <py* el-spec>, <pz* el-spec>, <s* el-spec>}+ (connects the AO specified by \cmd=2p=)
 \end{itemize}
\end{framed}
Obviously the regarding AO must have been set in order to connect them. This for example won't work:
\begin{lstlisting}
 \begin{MOdiagram} 
  \atom{left} { 1s = {  0; } }
  \atom{right}{ 1s = {  0; } }
  \molecule { 2sMO = {.75; , } }
 \end{MOdiagram}
\end{lstlisting}
The value used in \cmd=<energy gain>= determines how many \si{\centi\metre} the bonding MO lies below the lower AO or how many \si{\centi\metre} the anti-bondung MO lies above the higher AO.
% 
\begin{LTXexample}[pos=b]
 same level:
 \begin{MOdiagram}
  \atom{left} { 1s = {  0; up} }
  \atom{right}{ 1s = {  0; up} }
  \molecule { 1sMO = {.75; pair, } }
 \end{MOdiagram}

 different levels:
 \begin{MOdiagram}
  \atom{left} { 1s = {  0; up} }
  \atom{right}{ 1s = {  1; up} }
  \molecule { 1sMO = {.25; pair, } }
 \end{MOdiagram}
\end{LTXexample}
% 
Please be aware, that you have to specify \emph{two} such values with \cmd=2pMO=: the splitting of the \textsigma\ orbitals and the splitting of the \textpi\ orbitals.

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left} { 2p = { 0; up, up , } }
  \atom{right}{ 2p = { 1; up, up , } }
  \molecule { 2pMO = { 1.5, .75; pair, up, up , , , } } 
 \end{MOdiagram}
\end{LTXexample}

The complete MO diagram for triplett dioxygen now could look something like that:

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left}{
    1s = {0;pair},
    2s = {2;pair},
    2p = {5;pair,up,up}
  }
  \atom{right}{
    1s = {0;pair},
    2s = {2;pair},
    2p = {5;pair,up,up}
  }
  \molecule{
    1sMO  = {.5;pair,pair},
    2sMO  = {.5;pair,pair},
    2pMO  = {1.5,.5;pair,pair,pair,up,up,}
  }
 \end{MOdiagram}
\end{LTXexample}


\subsection{The Naming Scheme}\label{Namensgebung}
Since one wants to be able to put labels to the orbitals and since they are nodes in a tikzpicture, the internal naming scheme is important. It closely follows the function:
\begin{center}
\begin{MOdiagram}[distance=6cm,AO-width=20pt,labels-fs=\tt\footnotesize]
 \atom{left}{
   1s={0;},
   2s={2;},
   2p={5;,,},
   label={ 1sleft={1sleft}, 2sleft={2sleft}, 2pxleft={2pxleft}, 2pyleft={2pyleft}, 2pzleft={2pzleft} }
 }
 \atom{right}{
   1s={0;},
   2s={2;},
   2p={5;,,},
   label={ 1sright={1sright}, 2sright={2sright}, 2pxright={2pxright}, 2pyright={2pyright}, 2pzright={2pzright} }
 }
 \molecule{
   1sMO={.5;,},
   2sMO={.5;,},
   2pMO={1.5,.5;,,,,,},
   label={ 1sigma={1sigma}, 1sigma*={1sigma*}, 2sigma={2sigma}, 2sigma*={2sigma*}, 2psigma={2psigma}, 2psigma*={2psigma*}, 2piy={2piy}, 2piy*={2piy*}, 2piz={2piz}, 2piz*={2piz*} }
 }
\end{MOdiagram}
\end{center}
With these names it is possible to reference the orbitals with the known \TikZ commands:

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left} { 1s = {0; } }
  \atom{right}{ 1s = {0; } }
  \molecule { 1sMO = {.75; , } }
  \draw[<->,red,semithick] (1sigma) -- (1sigma*) ;
  \draw[red] (1sigma*) ++ (2cm,.5cm) node {splitting} ;
 \end{MOdiagram}
\end{LTXexample}

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left} { 1s = {0; } }
  \atom{right}{ 1s = {0; } }
  \molecule { 1sMO = {.75; , } }
  \draw[draw=blue,fill=blue!20,opacity=.5] (1sigma*) circle (8pt);
 \end{MOdiagram}
\end{LTXexample}


\subsection{Placing AO and MO Arbitrarily}
The standard orbitals are not always sufficient in order to draw a correct MO diagram. For example in the MO diagram of \ce{XeF2} one would need this part, that illustrates the interaction between the bonding and anti-bonding combination of two p orbitals of Flourine with one p orbital of Xenon:

\begin{center}
 \begin{MOdiagram}[names]
 \atom[\lewis{0.,F}\hspace*{5mm}\lewis{4.,F}]{left}{}
 \atom[Xe]{right}{}
 \molecule[\ce{XeF2}]{}
 \AO[a](1cm){s}{0;up}
 \AO[b](1cm){s}{.25;up}
 \AO[c](3cm){s}{-1;pair}
 \AO[d](3cm){s}{0;pair}
 \AO[e](3cm){s}{1.5;}
 \AO[f](5cm){s}{1.25;pair}
 \connect{ a & d , b & c , b & e , c & f , e & f }
 \node[right,xshift=4mm] at (c) {\footnotesize bonding};
 \node[above] at (d.90) {\footnotesize not bonding};
 \node[above] at (e.90) {\footnotesize anti-bonding};
\end{MOdiagram}
\end{center}
To create diagrams like this there is the following command, which draws a single AO:
\begin{framed}
 \cmd=\AO[<name>](<xshift>){<type>}{<energy>;<el-spec>}=
 \begin{itemize}\small
  \item\cmd=<name>= (o) name of the node
  \item\cmd=<xshift>= (o) vertical position of the Orbitals, a \TeX\ dimension.
  \item\cmd=<type>= (m) \cmd=s= or \cmd=p=
  \item\cmd=<AO-spec>= (m) specification of the AO
 \end{itemize}
\end{framed}
Depending on the \cmd=<type>= one s or three p porbitals are drawn.

\begin{LTXexample}
 \begin{MOdiagram}
  \AO{s}{0;}
  \AO(-20pt){p}{1;pair,up,down}
 \end{MOdiagram}
\end{LTXexample}

Please notice, that \cmd=<el-spec>= only awaits one specification with the type \cmd=s=, but three with the type \cmd=p=, separated with commas.

If one wants to place such an AO at the position of an atom, one has to know their \cmd=<xshift>=. They have these predefined values (also see section \ref{orbital-positionen}):\label{xshift}
\begin{itemize}
 \item atom left: \SI{1}{\centi\metre}
 \item molecule: \SI{3}{\centi\metre}
 \item atom right: \SI{5}{\centi\metre}
\end{itemize}

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left} {1s={0;}}
  \atom{right}{1s={0;}}
  \molecule {1sMO={1;,}}
  \AO(1cm){s}{2;pair}
  \AO(3cm){s}{2;pair}
  \AO(5cm){s}{2;pair}
 \end{MOdiagram}
\end{LTXexample}

Within the p orbitals there is an additional shift by \SI{20}{pt} per orbital. This is equivalent to a double shift by the length \cmd=AO-width= (see section \ref{option:AO-width}):

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left} {2p={0;,,}}
  \atom{right}{2p={0;,,}}
  % above the left atom:
  \AO(1cm)     {s}{ .5;pair}
  \AO(1cm-20pt){s}{  1;up}
  \AO(1cm-40pt){s}{1,5;down}
  % above the right atom:
  \AO(5cm)     {s}{ .5;pair}
  \AO(5cm+20pt){s}{  1;up}
  \AO(5cm+40pt){s}{1.5;down}
 \end{MOdiagram}
\end{LTXexample}

The AO created with \cmd=\AO= also can be connected. For this you can use the \TikZ command \cmd=\draw=, of course:

\begin{LTXexample}
 \begin{MOdiagram}
  \AO[a]{s}{0;} \AO[b](2cm){s}{1;}
  \AO[c]{s}{2;} \AO[d](2cm){s}{1.5;}
  \draw (a) -- (b) (c) -- (d);
 \end{MOdiagram}
\end{LTXexample}

However, if you want the lines to be drawn in the same style as the ones created by \cmd=\molecule=\footnote{which can be customized, see page \pageref{option:lines}}, you should use the command \cmd=\connect=.
\begin{framed}
 \cmd=\connect{<AO-connect>}=
 \begin{itemize}\small
  \item\cmd=<AO-connect>= (m) comma separated list of node name pairs connected with \cmd=&=.
 \end{itemize}
\end{framed}
This command expects a comma separated list of node name pairs, that are to be connected. The names have to be connected with a \cmd=&=:

\begin{LTXexample}
 \begin{MOdiagram}
  \AO[a]{s}{0;} \AO[b](2cm){s}{1;}
  \AO[c]{s}{2;} \AO[d](2cm){s}{1.5;}
  \connect{ a & b, c & d }
 \end{MOdiagram}
\end{LTXexample}

Some things still need to be said: \cmd=\connect= adds the anchor \cmd=east= to the first name and the anchor \cmd=west= to the second one. This means a connection only makes sense from the left to the right. However, you can add own anchors using the usual \TikZ way:

\begin{LTXexample}
 \begin{tikzpicture}
  \draw (0,0) node (a) {a} ++ (1,0) node (b) {b}
        ++ (0,1) node (c) {c} ++ (-1,0) node (d) {d} ;
  \connect{ a.90 & d.-90, c.180 & d.0 }
 \end{tikzpicture}
\end{LTXexample}


\subsection{The Positioning Scheme}\label{orbital-positionen}
The figure below shows the values of the $x$ coordinates of the orbitals, depending in the values of \cmd=<distance>= (\cmd=<dist>=) and \cmd=<AO-width>= (\cmd=<AO>=). In sections \ref{option:distance} and \ref{option:AO-width} these lengths and how they can be changed are discussed.

\begin{MOdiagram}[distance=6cm,AO-width=25pt,labels-fs=\tt\footnotesize,labels-style={text width=40pt,align=center}]
 \atom{left}{
   1s={0;},
   2s={3;},
   2p={8;,,},
   label={ 1sleft={1cm}, 2sleft={1cm}, 2pxleft={1cm}, 2pyleft={1cm - 2*<AO>}, 2pzleft={1cm - 4*<AO>} } }
 \atom{right}{
   1s={0;},
   2s={3;},
   2p={8;,,},
   label={ 1sright={1cm + <dist>}, 2sright={1cm + <dist>}, 2pxright={1cm+ <dist>}, 2pyright={1cm + <dist> + 2*<AO>}, 2pzright={1cm + <dist> + 4*<AO>} } }
 \molecule{
   1sMO={.75;,},
   2sMO={.75;,},
   2pMO={3,1;,,,,,},
   label={ 1sigma={.5*<dist> + 1cm}, 1sigma*={.5*<dist> + 1cm}, 2sigma={.5*<dist> + 1cm}, 2sigma*={.5*<dist> + 1cm}, 2psigma={.5*<dist> + 1cm}, 2psigma*={.5*<dist> + 1cm}, 2piy={.5*<dist> + 1cm - <AO>}, 2piy*={.5*<dist> + 1cm - <AO>}, 2piz={.5*<dist> + 1cm + <AO>}, 2piz*={.5*<dist> + 1cm + <AO>} }
 }
\end{MOdiagram}


\section{Customization}
\subsection{Environment Options}
There are some options with which the layout of the MO diagrams can be changed:
\begin{itemize}
 \item\cmd+style=<type>+ change the style of the orbitals and the connecting lines, section \ref{option:style}.
 \item\cmd+distance=<dim>+ distance betwen left and right atom, section \ref{option:distance}.
 \item\cmd+AO-width=<dim>+ change the width of orbitals, section \ref{option:AO-width}.
 \item\cmd+lines=<tikz>+ change the \TikZ style of the connecting lines, section \ref{option:lines}.
 \item\cmd+names=<bool>+ add captions to the atoms and the molecule, section \ref{option:names}.
 \item\cmd+labels=<bool>+ add default labels to the orbitals, section \ref{option:labels}.
 \item\cmd+labels-fs=<cs>+ change the font size of the labels, section \ref{option:labels-fs}.
 \item\cmd+labels-style=<tikz>+ change the \TikZ style of the labels, section \ref{option:labels-style}.
\end{itemize}
They all are discussed in the following sections. They are used either as option of the environment
\begin{lstlisting}
 \begin{MOdiagram}[<key = value>]
  ...
 \end{MOdiagram}
\end{lstlisting}
or as argument of the setup command
\begin{framed}
 \cmd+\MOsetup{<key = value>}+
 \begin{itemize}\small
  \item\cmd+<key = val>+ (m) comma separated key/value list
 \end{itemize}
\end{framed}

\subsubsection{Option \texttt{style}}\label{option:style}
There are four different styles, which can be chosen.
\begin{itemize}
 \item\cmd+style=plain+ \AOinline[style=plain]{pair} (default)
 \item\cmd+style=square+ \AOinline[style=square]{pair}
 \item\cmd+style=round+ \AOinline[style=round]{pair}
 \item\cmd+style=fancy+ \AOinline[style=fancy]{pair}
\end{itemize}
Let's take the MO diagram of \ce{H2} to illustrate the different styles:

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[style=plain]% Default
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}
\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[style=square]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}
\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[style=round]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}
\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[style=fancy]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}


\subsubsection{Option \texttt{distance}}\label{option:distance}
Depending on labels and captions the \SI{4}{\centi\metre} by which the right and left atom are separated can be too small. With \cmd+distance=<dim>+ the length can be adjusted. With this, the position of the right atom is changed to \cmd=1cm + <dim>= and the position of the molecule is changed to \cmd=0.5*(1cm + <dim>)=, also see page Seite \pageref{xshift} and section \ref{orbital-positionen}.

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[distance=6cm]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}


\subsubsection{Option \texttt{AO-width}}\label{option:AO-width}
The length \cmd=AO-width= sets the length of the horizontal line in a orbital displayed with the \cmd=plain= style. It's default value is \SI{10}{pt}.

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[AO-width=15pt]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}
\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[style=fancy,AO-width=15pt]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}

By changing the value of \cmd=AO-width= the positions of the p and the \textpi\ orbitals also change, see section \ref{orbital-positionen}.

\subsubsection{Option \texttt{lines}}\label{option:lines}
The option \cmd=lines= can be used to modify the \TikZ style of the connecting lines:

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[lines={gray,thin}]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}


\subsubsection{Option \texttt{names}}\label{option:names}
If you use the option \cmd=names=, the atoms and the molecule get captions, if you have used the optional \cmd=<name>= argument of \cmd=\atom= and/or \cmd=\molecule=.

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[names]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}


\subsubsection{Option \texttt{labels}}\label{option:labels}
If you use the option \cmd=labels=, predefined labels are written below the orbitals. These labels can be changed, see section \ref{key:label}.

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[labels]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}


\subsubsection{Option \texttt{labels-fs}}\label{option:labels-fs}
Labels are set with the font size \cmd=\small=. If you want to change that, you can use the option \cmd=labels-fs=.

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[labels,labels-fs=\footnotesize]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}

This also allows you to change the font style or font shape of the labels.

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[labels,labels-fs=\sffamily\footnotesize]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}


\subsubsection{Option \texttt{labels-style}}\label{option:labels-style}
The option \cmd=labels-style= changes the \TikZ style of the nodes, within which the labels are written.

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[labels,labels-style={blue}]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{ 1sMO = {.75;pair,} }
 \end{MOdiagram}
\end{LTXexample}


\subsection{\texttt{\textbackslash atom} and \texttt{\textbackslash molecule} Specific Customizations}
\subsubsection{The \texttt{label} Key}\label{key:label}
If you don't want to use the predefined labels, change single labels or use only one or two labels, you can use the key \cmd=label=. This key is used in the \cmd=\atom= and  \cmd=\molecule= commands in the \cmd=<AO-spec>= or \cmd=<MO-spec>= argument, respectively. The key awaits a comma separated key/value list. The names mentioned in section \ref{Namensgebung} are used as keys to specify the AO, that you want to label.

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[labels-fs=\footnotesize]
  \atom[H]{left} { 1s = {0;up} }
  \atom[H]{right}{ 1s = {0;up} }
  \molecule[\ce{H2}]{
    1sMO  = {.75;pair,},
    label = { 1sigma = {bonding MO} }
  }
 \end{MOdiagram}
\end{LTXexample}
\begin{LTXexample}
 \begin{MOdiagram}[style=square,distance=6cm]
  \atom{left} { 1s = {0;up} }
  \atom{right}{ 1s = {0;up} }
  \molecule{
    1sMO  = {.75;pair,} ,
    label = {
      1sigma  = $\sigma$,
      1sigma* = $\sigma^*$
    }
  }
  \node[right] at (1sigma.-45) {bonding};
  \node[right] at (1sigma*.45) {anti-bonding};
 \end{MOdiagram}
\end{LTXexample}


\subsubsection{The \texttt{color} Key}\label{key:color}
Analogous to the \cmd=label= key the \cmd=color= key can be used to display coloured electrons:

\begin{LTXexample}
 % use package 'mhchem'
 \begin{MOdiagram}[labels-fs=\footnotesize]
  \atom[H]{left}{
    1s = {0;pair},
    color = { 1sleft = blue }
  }
  \atom[H]{right}{
    1s = {0;pair},
    color = { 1sright = red }
  }
  \molecule[\ce{H2}]{
    1sMO  = {.75;pair,pair},
    label = { 1sigma = {bonding MO} },
    color = { 1sigma = green, 1sigma* = cyan }
  }
 \end{MOdiagram}
\end{LTXexample}


\subsection{Energy Axis}
Last but not least one might want to add an energy axis to the diagram. For this there is the command \cmd=\EnergyAxis=.
\begin{framed}
 \cmd+\EnergyAxis[<key = val>]+
 \begin{itemize}\small
  \item\cmd+<key = val>+ (o) key/value pairs to modify the axis
 \end{itemize}
\end{framed}

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left} { 1s = {0;up} }
  \atom{right}{ 1s = {0;up} }
  \molecule{ 1sMO = {.75;pair,} }
  \EnergyAxis
 \end{MOdiagram}
\end{LTXexample}

For the time beeing there are two keys to modify the axis.
\begin{framed}
 \begin{itemize}
  \item\cmd+title=<title>+ axis label (default: \cmd=energy=).
  \item\cmd+head=<tikz-arrow-head>+ arrow head; you can use the arrow heads specified in the \TikZ library \paket{arrows} (pgfmanual v2.10 pages 256ff.) (default: \cmd=>=).
 \end{itemize}
\end{framed}

\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left} { 1s = {0;up} }
  \atom{right}{ 1s = {0;up} }
  \molecule{ 1sMO = {.75;pair,} }
  \EnergyAxis[title]
 \end{MOdiagram}
\end{LTXexample}
\begin{LTXexample}
 \begin{MOdiagram}
  \atom{left} { 1s = {0;up} }
  \atom{right}{ 1s = {0;up} }
  \molecule{ 1sMO = {.75;pair,} }
  \EnergyAxis[title=E,head=stealth]
 \end{MOdiagram}
\end{LTXexample}


\subsection{Examples}
% 
\begin{LTXexample}[pos=b]
 % use packages 'mhchem' (and 'textgreek' loaded by 'MOdiagram')
 \begin{figure}
  \centering
  \begin{MOdiagram}[style=square,labels,names,AO-width=8pt,labels-fs=\footnotesize]
   \atom[\ce{O_a}]{left}{
     1s = {0;pair},
     2s = {2;pair},
     2p = {5;pair,up,up}
   }
   \atom[\ce{O_b}]{right}{
     1s = {0;pair},
     2s = {2;pair},
     2p = {5;pair,up,up}
   }
   \molecule[\ce{O2}]{
     1sMO  = {.5;pair,pair},
     2sMO  = {.5;pair,pair},
     2pMO  = {1.5,.5;pair,pair,pair,up,up,},
     color = { 2piy*=red, 2piz*=red }
   }
   \EnergyAxis
  \end{MOdiagram}
  \caption{MO diagram of $^3$\textSigma-\ce{O2}.}
 \end{figure}
\end{LTXexample}
\begin{LTXexample}[pos=b]
 % use package 'chemfig'
 \begin{figure}
  \centering
  \begin{MOdiagram}[style=fancy,distance=7cm,AO-width=15pt,labels]
   \atom[N]{left}{
     2p = {0;up,up,up}
   }
   \atom[O]{right}{
     2p = {2;pair,up,up}
   }
   \molecule[NO]{
     2pMO = {1.8,.4;pair,pair,pair,up,,},
     color = { 2piy*=red }
   }
   \EnergyAxis[title]
  \end{MOdiagram}
  \caption{Part of the MO diagram of \protect\Lewis{4.,NO}.}
 \end{figure}
\end{LTXexample}
% 

\end{document}