\chapter[\pxm Customization]{\pxm Customization: Adding Atom and
Chemistry Definitions}
\label{chap:polyxmass-customization}

\newcommand{\pxmcustom}{\filename{/home/rusconi/pxm-custom}\xspace}
\newcommand{\pxmcfgdir}{\filename{/home/rusconi/.polyxmass}\xspace}
\newcommand{\pxmatoms}
{\filename{/usr/share/polyxmass/atom-defs/atoms.xml}\xspace}

This chapter will guide the user through a step-by-step procedure to
learn how to customize the \pxm software suite by adding atom
definitions and polymer chemistry definitions for a \emph{local and
  individual} use.

\renewcommand{\sectitle}{Getting The Substrate Of Our Experiment}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

The example that we will make will be based on part of the contents of
the \pxmdata package (the ``saccharide'' polymer chemistry
definition), that the user is invited to download \emph{without
  installing it}. The best way to go is to download the ``source
tarball'': the file \filename{\pxmdatang-\pxmdataver.tar.gz} and
perform the following procedure to unpack it in a suitable place:

\begin{itemize}
\item Copy that file to a directory where you have write
  permissions:\footnote{I usually work by making a tmp directory in my
    home directory and copying there the files that correspond to
    temporary tasks; thus our tarball file would have the following
    absolute name:
    \filename{/home/rusconi/tmp/\pxmdatang-\pxmdataver.tar.gz}.}
  
  \begin{mynoindent}
    \begin{alltt}
      mkdir /home/rusconi/tmp \kbdEnterKey
      cp \pxmdatang{}-\pxmdataver.tar.gz /home/rusconi/tmp \kbdEnterKey
    \end{alltt}
  \end{mynoindent}
  
\item Unpack the \fileformat{tar.gz} archive into the current working
  directory:

  \begin{mynoindent}
    \begin{alltt}
      tar xvzf \pxmdatang{}-\pxmdataver.tar.gz \kbdEnterKey
    \end{alltt}
  \end{mynoindent}
  
\item Now go to the newly created directory:

  \begin{mynoindent}
    \begin{alltt}
      cd \pxmdatang{}-\pxmdataver \kbdEnterKey
    \end{alltt}
  \end{mynoindent}
  
  \item Check that there is effectively the directory with the
    ``saccharide'' polymer chemistry definition data:

  \begin{mynoindent}
    \begin{alltt}
      ls polchem-defs/saccharide \kbdEnterKey
    \end{alltt}
  \end{mynoindent}
  
  You should get a rather large listing of files, and if you look well
  at them you'll see two files of interest: \filename{saccharide.xml}
  and \filename{monicons.dic}. Also, a \filename{sounds} directory
  should contain empty sound files (filename extensions are
  \filename{.ogg}) and a dictionary file (\filename{sounds.dic}).
  Great, we have the substrate with which we will demonstrate how to
  bring new polymer chemistry definitions to the \pxm software suite!

\end{itemize}

\renewcommand{\sectitle}{Creating A New Polymer Chemistry Definition}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}


\noindent At this point we know we can go on with our procedure. We
should immediately create a directory where we will install the
``saccharide'' polymer chemistry definition-related files:

\begin{mynoindent}
  \begin{alltt}
    mkdir \pxmcustom \kbdEnterKey
  \end{alltt}
\end{mynoindent}

\noindent Now we can copy the ``saccharide'' polymer chemistry
definition directory in our juste-made directory (we are still in the
\filename{\pxmdatang{}-\pxmdataver} directory):

\begin{mynoindent}
  \begin{alltt}
    cp -rpf \filename{polchem-defs/saccharide} \pxmcustom \kbdEnterKey
  \end{alltt}
\end{mynoindent}

Right, we now have our new ``saccharide'' polymer chemistry definition
data; we could have made them from scratch, but we happen to be lazy
so we copied them from an available package\dots\ We now have to start
the configuration process that will let \pxm know that we have brought
one more polymer chemistry definition. To do that, we'll have to
create (if it does not exist already) the \filename{.polyxmass}
directory in our home directory.\footnote{The home directory, in
  \OSname{UNIX} systems, is the directory where the user finds himself
  once logged onto the system. Usually, it is something like
  \filename{/home/\emph{logname}}, with \emph{logname} being the
  username used to log onto the system (for me that's \emph{rusconi}).
  Furthermore, the home directory of a user is visible in the
  \filename{/etc/passwd} file, which lists it for the user
  \emph{rusconi} in this way (try for yourself):

  \begin{alltt}
    rusconi:x:1000:1000:Filippo Rusconi:/home/rusconi:/bin/bash
  \end{alltt}.} 

Also, we should make the \filename{polchem-defs} directory inside it.
So these are the command lines:

\begin{mynoindent}
  \begin{alltt}
    mkdir \pxmcfgdir \kbdEnterKey
    mkdir \pxmcfgdir{}/polchem-defs \kbdEnterKey
  \end{alltt}
\end{mynoindent}

At this point, we should mimick the file-system hierarchy that we have
already described for the \filename{/etc/polyxmass} directory, by
creating a \filename{rusconi-\emph{polchem-defs-cat}} where we'll add
the line corresponding to the new ``saccharide'' polymer chemistry
definition, as we have seen in the chapter about \pxmcommon (note the
compulsory \emph{polchem-defs-cat} suffix in the catalogue filename):

\begin{mynoindent}
  \begin{alltt}
    cd \pxmcfgdir{}/polchem-defs \kbdEnterKey
    touch rusconi-\emph{polchem-defs-cat} \kbdEnterKey
  \end{alltt}
\end{mynoindent}

Now use an editor to put the following line in this file (each polymer
chemistry definition name and its corresponding data \emph{must} be on
a single line without space; here, for clarity the line was broken, as
symbolised with the ``\verb|\\|'' characters that are absent in the
file). \emph{Remember to terminate the text line with a carriage
  return, symbolized with `\kbdEnterKey' below!}:

\begin{mynoindent}
  \begin{alltt}
    saccharide=/home/rusconi/pxm-custom/saccharide/saccharide.xml\verb|\\|
    % /home/rusconi/pxm-custom/saccharide \kbdEnterKey
  \end{alltt}
\end{mynoindent}

If we started \pxm now, we would be able to partially enjoy the
result: when trying to load the new polymer chemistry definition in
\pxd, we would get the file-chooser window shown on
Figure~\ref{fig:customize-new-polchem-def}.

\begin{figure}
\begin{center}
  \includegraphics [scale=2]
  {figures/raster/customize-new-polchem-def.png}
\end{center}
\caption[The new polymer chemistry definition]{\textbf{The new polymer
    chemistry definition} The new polymer chemistry definition
  ``saccharide'' is now known to the system, since we have edited the
  \filename{\pxmcfgdir{}/polchem-defs/rusconi-polchem-defs-cat}
  catalogue file to that precise end.}
\label{fig:customize-new-polchem-def}
\end{figure}

However, if we were courageous enough to select ``saccharide'' from
the listview and click the \guilabel{Validate} button, we would find
an error because \pxm does not yet know what atom definition should be
used with this polymer chemistry definition. The error message that
is sent to the terminal window is the following:

\begin{mynoindent}
  \begin{alltt}
    ** (polyxmass:14734): CRITICAL **: polyxdef-ui-polchemdef.c@225:
    failed setting the proper atom definition name for current 
    polymer definition to combo list
  \end{alltt}
\end{mynoindent}

\renewcommand{\sectitle}{Creating A New Atom Definition}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

What this error message is saying, is that the program could not tell
what atom definition was to be loaded for us to correctly display (and
supposedly edit) the polymer chemistry definition that was selected.
That means that we still have some work to do: we still have to
provide an atom definition and register it to \pxm.

We could ---of course--- just tell \pxm that the atom definition to be
used when working with the ``saccharide'' polymer chemistry definition
is the ``basic'' atom definition that is shipped with the \pxmcommon
package. But since we are making a tutorial hands-on procedure, we'll
fake the system into thinking that the ``saccharide'' polymer
chemistry definition requires a specific atom definition called
``mysugar''. But we do not want to write that atom definition file
\textit{ex nihilo}, so we'll just make a copy of the
\filename{atoms.xml} atom definition file that was shipped with the
\pxmcommon package.  On my system, the \pxmcommon package was
installed in the \filename{/usr} system directory tree, so I'll find
that \filename{atoms.xml} file there, and copy it to
\filename{\pxmcustom}, like this (on a \emph{single} line, please):

\begin{mynoindent}
  \begin{alltt}
    cp \pxmatoms 
                \pxmcustom/for-sugar.xml \kbdEnterKey
  \end{alltt}
\end{mynoindent}

\noindent At this point we'll have to inform the \pxm software suite
that we have a new atom definition, named ``mysugar'', of which the
file is 

\filename{\pxmcustom/for-sugar.xml}.

\medskip

For this, we'll have to continue mimicking the file-system hierarchy
that we have already described for the \filename{/etc/polyxmass}
directory, by creating an \filename{atom-defs} directory in the user's
\filename{\pxmcfgdir{}} directory. Inside this directory, we will have
to create the \filename{rusconi-\emph{atom-defs-cat}} file where we'll
add the line corresponding to our new ``mysugar'' atom definition, as
we have seen in the chapter about \pxmcommon (note the compulsory
\emph{atom-defs-cat} suffix in the catalogue filename):

\begin{mynoindent}
  \begin{alltt}
    mkdir \pxmcfgdir{}/atom-defs \kbdEnterKey
    cd \pxmcfgdir{}/atom-defs \kbdEnterKey
    touch rusconi-\emph{atom-defs-cat} \kbdEnterKey
  \end{alltt}
\end{mynoindent}

Now we have to use an editor, so that we can put the following line in
this file. \emph{Remember to terminate the line with a carriage
  return, symbolized with `\kbdEnterKey' below!}

\begin{mynoindent}
  \begin{alltt}
    mysugar=/home/rusconi/pxm-custom/for-sugar.xml \kbdEnterKey
  \end{alltt}
\end{mynoindent}


\renewcommand{\sectitle}{The Polymer Chemistry Definition--Atom Definition Dictionary}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}


At this point, we have told \pxm that we have a new atom definition
file, but we still have to make sure this atom definition is actually
loaded each time a ``saccharide'' polymer chemistry definition is
used. For this, we already know that we have to edit a dictionary file
so that we can make the correspondence between the polymer chemistry
definition and the atom definition. This dictionary file should be
located, along with the polymer chemistry definition files, in
\filename{\pxmcfgdir{}/polchem-defs}, and be named, as in
\filename{/etc/polyxmass/polchem-defs},
\filename{rusconi-\emph{polchem-defs-atom-defs-dic}} (note the
compulsory \emph{polchem-defs-atom-defs-dic} suffix in the dictionary
filename):

\begin{mynoindent}
  \begin{alltt}
    cd \pxmcfgdir{}/polchem-defs/
    touch rusconi-\emph{polchem-defs-atom-defs-dic} \kbdEnterKey
  \end{alltt}
\end{mynoindent}

Now use an editor to put the following line in this file.
\emph{Remember to terminate the line with a carriage return,
  symbolized with `\kbdEnterKey' below!}:

\begin{mynoindent}
  \begin{alltt}
    saccharide=mysugar \kbdEnterKey
  \end{alltt}
\end{mynoindent}

\renewcommand{\sectitle}{Enjoying The New Polymer Chemistry Definition}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

At this point, the user has successfully configured the new polymer
chemistry definition and can start enjoying it: if we try to open, in
a new \progname{\pxmng{}} session (\progname{\pxmng{}} needs to be
restarted because all the files we have been configuring are read at
startup), the ``saccharide'' polymer chemistry definition, we can do
it successfully, as shown on
Figure~\ref{fig:customize-saccharide-polchem-def-OK}.

\begin{figure}
\begin{center}
  \includegraphics [scale=2]
  {figures/raster/customize-saccharide-polchem-def-OK.png}
\end{center}
\caption[Loading the newly installed polymer chemistry
definition]{\textbf{Loading the newly installed polymer chemistry
    definition} Finally the polymer chemistry definition
  ``saccharide'' can be opened from disk using the \pxd module, as all
  the configurations were performed. Note the \guilabel{Atom
    Definition To Use} data at the top of the window, which indicate
  with what atom definition this polymer chemistry definition will
  work.}
\label{fig:customize-saccharide-polchem-def-OK}
\end{figure}

Finally, since we have an example ``saccharide'' sequence in the data
that we initially unpacked in
\filename{/home/rusconi/tmp/\pxmdatang{}-\pxmdataver}, we can try to
open the ``saccharidic'' polymer sequence file
\filename{pol-seqs/ose-sample.pxm}. That works perfectly, as shown on
Figure~\ref{fig:customize-saccharide-pol-seq-OK}.

\begin{figure}
\begin{center}
  \includegraphics [scale=2]
  {figures/raster/customize-saccharide-pol-seq-OK.png}
\end{center}
\caption[Loading a ``saccharidic'' polymer sequence]{\textbf{Loading a
    ``saccharidic'' polymer sequence} Since the ``saccharide'' polymer
  chemistry definition is fully configured, we can load from disk a
  polymer sequence of that chemistry definition.}
\label{fig:customize-saccharide-pol-seq-OK}
\end{figure}