% arara: pdflatex
% arara: pdflatex
% --------------------------------------------------------------------------
% the BOHR package
% 
%   simple atom representation according to the Bohr model
% 
% --------------------------------------------------------------------------
% Clemens Niederberger
% Web:    https://bitbucket.org/cgnieder/bohr/
% E-Mail: contact@mychemistry.eu
% --------------------------------------------------------------------------
% Copyright 2012 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.
% --------------------------------------------------------------------------
% The bohr package consists of the files
%  - bohr.sty
%  - bohr_en.tex, bohr_en.pdf
%  - bohr_elements_english.def, bohr_elements_german.def
%  - README
% --------------------------------------------------------------------------
% If you have any ideas, questions, suggestions or bugs to report, please
% feel free to contact me.
% --------------------------------------------------------------------------
%
% if you want to compile this documentation you'll need my `cnltx` bundle
% which you can get here:
%    https://github.com/cgnieder/cnltx/
%
\documentclass[load-preamble+]{cnltx-doc}
\usepackage[utf8]{inputenc}
\usepackage{bohr}

\setcnltx{
  package = bohr ,
  authors = Clemens Niederberger ,
  email   = contact@mychemistry.eu ,
  url     = https://bitbucket.org/cgnieder/bohr/ ,
  add-cmds = {
    atomicnumber,
    bohr,
    DeclareAtomName,
    DeclareAtomSymbol,
    DeclareElectronDistribution,
    elconf,
    elementname,
    elementsymbol,
    setatomname,setatomsymbol,
    setelectrondistribution,
    setbohr,
    writeelconf,
    Z
  } ,
  add-silent-cmds = ch ,
  abstract = {%
    This package provides means for the creation of simple
    Bohr models of atoms up to the atomic number 112.  Additionally commands
    are provided to convert atomic numbers to element symbols or element names
    and vice versa.\par
    The package is inspired by a question on
    \url{http://tex.stackexchange.com/}:
    \href{http://tex.stackexchange.com/questions/73410/draw-bohr-atomic-model-with-electron-shells-in-tex}%
    {Draw Bohr atomic model with electron shells in \TeX?}%
  } ,
  index-setup = {
     othercode = \footnotesize ,
     level = \addsec ,
     noclearpage
  } ,
  makeindex-setup = {
     columns = 3 ,
     columnsep = 1em
  }
}

% \microtypesetup{tracking=scshape}

\defbibheading{bibliography}{\addsec{References}}

\newpackagename\BOHR{bohr}

\usepackage{chemmacros}

\begin{document}

\section{Licence and Requirements}
\license

The \BOHR\ package loads and needs the packages
\needpackage[graphics]{pgf}~\cite{pkg:pgf} and
\pkg{cnltx-base}\footnote{\CTANurl{cnltx}}~\cite{bnd:cnltx}.

\section{Options}
Every option described in the manual can also be used as package option.
Options are indicated as \option*{option} and are all key/value like options.
Some options can be set without value, too.  Then the
\code{\default{underlined}} value is used.

\section{Usage}
\BOHR\ is used like any other \LaTeXe\ package:
\begin{sourcecode}
  \usepackage{bohr}
\end{sourcecode}

The main command, \cs{bohr}, creates the models:
\begin{commands}
 \command{bohr}[\oarg{num of shells}\marg{num of electrons}\marg{atom name}]
   The main command.  The mandatory arguments take the number of electrons to
   be printed and the atom symbol that is printed in the center.
\end{commands}

This is described best by an example:
\begin{example}[side-by-side]
  \bohr{3}{Li}
\end{example}
There is not much more to it.  Another example using the optional argument:
\begin{example}[side-by-side]
  \bohr[2]{2}{$\mathrm{Li^+}$}
\end{example}

\section{Customization}
\BOHR\ provides a handful of options to customize the appearance:
\begin{commands}
  \command{setbohr}[\marg{options}]
    Options are set in a key/value syntax using this command.
\end{commands}
\begin{options}
  \keybool{insert-symbol}\Default{false}
    If set to \code{true} \BOHR\ will insert the atomic symbol suiting to the
    given electron number if \emph{no} third argument is given.
  \keybool{insert-number}\Default{false}
    If set to \code{true} \BOHR\ will use the appropriate number of electrons
    for the given element symbol in the third argument if \emph{no} second
    argument is given.  This of course only works if the third argument is one
    of the 112 element symbols.
  \keybool{insert-missing}\Default{false}
    Sets both \option{insert-symbol} and \option{insert-number}.
  \keyval{atom-style}{code}\Default
    This code will be placed immediatly before the third argument of
    \cs{bohr}.  The last macro in it may need one argument.
  \keyval{name-options-set}{tikz option}\Default
    This value is passed to the options of the \cs*{node} the third argument
    of \cs{bohr} is placed in.
  \keyval{name-options-add}{tikz options}\Default
    This value will be added to options set with \option{name-options-set}.
  \keyval{nucleus-options-set}{tikz options}{}
  \Default{draw=black!80,fill=black!10,opacity=.25}
    This value is passed to the options of the \cs*{draw} command that draws
    the circle around the name-node.
  \keyval{nucleus-options-add}{tikz options}\Default
    This value will be added to options set with \option{nucleus-options-set}.
  \keyval{nucleus-radius}{dimension}\Default{1em}
    The radius of the circle around the name-node.
  \keyval{electron-options-set}{tikz options}\Default{blue!50!black!50}
    This value is passed to the options of the \cs*{fill} command that draws
    the electrons.
  \keyval{electron-options-add}{tikz options}\Default
    This value will be added to options set with \option{electron-options-set}.
  \keyval{electron-radius}{dimension}\Default{1.5pt}
    The radius of the circles that represent the electrons.
  \keyval{shell-options-set}{tikz options}\Default{draw=blue!75,thin}
    This value is passed to the options of the \cs*{draw} command that draws
    the circles that represent the shells.
  \keyval{shell-options-add}{tikz options}\Default
    This value will be added to options set with \option{shell-options-set}.
  \keyval{shell-dist}{dimension}\Default{1em}
    The distance between the nucleus and the first shell and between subsequent
    shells.
  \keyval{language}{language}\Default
    \sinceversion{0.2d}Select the language used for the element names manually
    rather than letting \BOHR\ select it automatically.  This option must be
    used as package option or in the preamble in order to have an effect.
    Currently provided languages are \code{English}, \code{French} and
    \code{German}.  If this option is not used the document language at the
    end of the preamble (as set by \pkg{babel} or \pkg{polyglossia}) is
    used.
  \keychoice{distribution-method}{periodic,quantum}\Default{quantum}
    \sinceversion{0.3}Determines how the electrons are distributed on the
    shells.  \code{periodic} distributes the electrons 2-8-8-18-18-32-32, \ie,
    according to the place of the corresponding atom in the periodic table of
    elements.  \code{quantum} distributes the electrons according the the
    electron configuration of the corresponding atom where each shell
    represents the main quantum number.  \ch{Pd} for example has the
    configuration $1s^22s^22p^63s^23p^63d^{10}4s^24p^64d^{10}$ and would get
    two electrons on the first shell, 8~electrons on the second, and
    18~electrons each on the third and fourth.
\end{options}

\begin{example}
  \setbohr{name-options-set={font=\footnotesize\sffamily}}
  \bohr{2}{He} \bohr{7}{N}
\end{example}

\begin{example}
  % uses package `chemmacros'
  \setbohr{atom-style={\footnotesize\sffamily\ch}}
  \bohr{0}{H+} \bohr{10}{F-}
\end{example}

\begin{example}[side-by-side]
  \setbohr{
    shell-options-add = dashed,
    shell-dist        = .5em,
    insert-missing
  }
  \bohr{6}{} \bohr{}{K}
\end{example}

\setbohr{atom-style = \ch}

\section{Additional Commands}\label{sec:additional-commands}
\BOHR\ provides some additional commands that return the element symbol or the
element name to a given atomic number and vice versa.
\begin{commands}
  \command{elementsymbol}[\Marg{\choices{\meta{atomic number},\meta{element
        name}}}]
    Returns the element symbol for a given atomic number or element name.\\
    \verbcode+\elementsymbol{80}+: \elementsymbol{80};\\
    \verbcode+\elementsymbol{rhenium}+: \elementsymbol{rhenium}.\\
    The symbols are printed according to \option{atom-style}.
  \command{elementname}[\Marg{\choices{\meta{atomic number},\meta{element
        symbol}}}]
    Returns the element name for a given atomic number or element symbol.\\
    \verbcode+\elementname{80}+: \elementname{80};\\
    \verbcode+\elementname{Rh}+: \elementname{Rh}.
  \command{atomicnumber}[\Marg{\choices{\meta{element name},\meta{element
        symbol}}}]
    Returns the atomic number for a given element name or element symbol.\\
    \verbcode+\atomicnumber{Hg}+: \atomicnumber{Hg};\\
    \verbcode+\atomicnumber{rhenium}+ \atomicnumber{rhenium}.
  \command{Z}
    If this command isn't defined at begin document it is available as an
    alias of \cs{atomicnumber}.
  \command{elconf}[\Marg{\choices{\meta{atomic number},\meta{element
        symbol},\meta{element name}}}]
    \sinceversion{0.4}Prints the electron configuration of the given
    element.\\
    \verbcode+\elconf{Cu}+: \elconf{Cu};\\
    \verbcode+\elconf{copper}+: \elconf{copper};\\
    \verbcode+\elconf{29}+: \elconf{29}.\\
    Currently there is no way to get the shortened version
    (\eg\ $[\elementsymbol{18}]3d^{10}4s^1$ for \elementname{29}).
  \command{writeelconf}[\marg{electron distribution}]
    \sinceversion{0.4}Writes the electron distribution \meta{electron
      distribution}.  The input is the same as described below for
    \cs{setelectrondistribution}.\\
    \verbcode=\writeelconf{2,2+6,2+6+7}=: \writeelconf{2,2+6,2+6+7}.
  \command{setatomsymbol}[\marg{atomic number}\marg{atom symbol}]
    \sinceversion{0.4}This sets the symbol associated with the atom number
    \meta{atomic number}.
  \command{setatomname}[\marg{atomic number}\marg{element name}]
    \sinceversion{0.4}This sets the element name associated with the atom
    number \meta{atomic number}.
  \command{setelectrondistribution}[\marg{atomic number}\marg{electron
    distribution}]
    \sinceversion{0.4}This set the electron distribution associated with the
    atom number \meta{atomic number}.  \meta{electron distribution} is a
    comma-separated list of the number of electrons placed on each shell from
    inner to outer shell.  For example
    \verbcode+\setelectrondistribution{3}{2,0,1}+ would be an excited
    Lithium.  The distribution thus declared is only used for drawing when
    \keyis{distribution-method}{quantum} but is also used by \cs{elconf}.  The
    number of electrons with the same principal quantum number but a different
    angular quantum number are separated with a \code{+} ordered by the
    angular quantum number, \ie, first $s$, then $p$, then $d$, and then $f$.
    \elementname{29}'s distribution would be declared like this:
    \verbcode=\setelectrondistribution{29}{2,2+6,2+6+10,1}=.\par
    A declaration with \verbcode=\setelectrondistribution{29}{2,8,18,1}= would
    work but then \cs{elconf}\Marg{29} would give the wrong results.
\end{commands}

\begin{example}
  The elements \elementname{F}, \elementname{Cl}, \elementname{Br},
  \elementname{I} and \elementname{At} are called \emph{halogens}.
\end{example}

\section{Internal Commands}\label{sec:internal-commands}
The element properties used by \BOHR\ are defined through the following commands:
\begin{commands}
  \command{DeclareAtomSymbol}[\marg{atomic number}\marg{atom symbol}]
    The package file contains 112~lines like the following:
    \verbcode+\DeclareAtomSymbol{29}{Cu}+.  They associate atomic number with
    the corresponding atom symbol.  This is the internal equivalent to
    \cs{setatomsymbol}.
  \command{DeclareAtomName}[\marg{atomic number}\marg{element name}]
    \BOHR\ comes with a few language files named
    \code{bohr\_elements\_\meta{language}.def}.  They contain of 112~entries
    like \verbcode+\DeclareAtomName{29}{Copper}+ which associate atomic number
    and element name.  This is the internal equivalent to \cs{setatomname}.
  \command{DeclareElectronDistribution}[\marg{atomic number}\marg{electron
    distribution}]
    The \meta{electron distribution} is a comma separated list of integers
    which determines how the electrons are distributed on the shells when
    \keyis{distribution-method}{quantum}.  The package file contains
    112~entries like \verbcode=\DeclareElectronDistribution{29}{2,2+6,2+6+10,1}=.
    This is the internal equivalent to \cs{setelectrondistribution}.
\end{commands}

\end{document}
