CpcSim > Reference Manual

Basics
cpcsim
columnheads.pl
draweffl.pl
drawfull.pl
comp.pl
stammer.pl
ppmtompeg.pl

The Reference Manual applies to version 0.0.1.5 of CpcSim.

Basics

Version 0.0.1.5 of CpcSim is only able to deal with Strong Ion-eXchanger CPC (SIXCPC, or SX) problems. The sample is made of a mixture of monoacids that are always present in their ionized (basic) form.

The ion-exchanger is a quaternary ammonium cation, like the benzalkonium ion. It is initially associated to the chloride anion that acts as retainer. The analyte anions have more affinity towards the exchanger than chloride.

The analytes may be either injected as their benzalkonium ion-pairs in the stationary phase or injected as sodium salts in the mobile phase. In the latter case, some pure mobile phase is injected before the beginning of the chromatographic development itself.

Development is initiated by the pumping of mobile phase to which sodium iodide is added. Iodide anions have more affinity towards the exchanger than any analyte anion. There is no (neutral) hydroiodic acid in the system.

The simulation of the chromatographic process requires the knowledge of the thermodynamic equilibrium constants that rule the exchange of ions around the exchanger, as well as, if needed, the knowledge of the association constants of (lipophilic) analyte anions in the (polar) mobile phase.

The theory of thermodynamic equilibration within a biphasic system is summarized in cpcmodel-en.pdf or in cpcmodel-fr.pdf, depending on the reader's linguistic ability.

cpcsim

Syntax
<cpc> sections

Syntax

Syntax

The "cpcsim" command takes a single argument, the name of the file that describes the problem that will be solved. The syntax of the cpcsim input files follows the XML rules. The param.xml file may be consulted to get an idea of the input data file layout. The general framework is:

    <?xml version="1.0"?>
    <cpc>
    .
    .
    </cpc>
   

and comments may be inserted as

    <!-- some comment -->
   

The input file is divided in sections placed between the opening <cpc> tag and the closing </cpc> tag. Each section is referenced by its name, starts by an opening tag and ends with a closing tag, following the syntax of the global cpc section.

A section may either directly contain a cpcsim parameter value or be a container for other sections. The former are "leaf" sections and the latter are "node" sections. The opening tag of a "leaf" section must define the type of the parameter that will follow. Parameter types are either "string" for literal constants, "int" for integer numbers and "real" for floating point numbers. The section that gives to number of cells in the column is therefore written as:

    <number_of_cells type="int">
            40
    </number_of_cells>
   

A "leaf" tag without type information is simply ignored! Two sub-nodes of any node cannot have the same name. The order in which the sub-nodes of a node appear has no importance.

A comment node of type "string" may be inserted for data file documentation. An "experiment" leaf section of type "string" must be present to indicate the experiment type. The only possible value for "experiment" is "SX", standing for "Strong eXchanger", because, to date, nothing else is implemented in CpcSim. Apart "comment" and "experiment" all sections that are directly placed inside of "cpc" are node sections.

<cpc> sections

<experiment>

The only possible value in the <experiment type="string"> section is "SX".

<column>

The <column> section contains two mandatory sub-sections:

Experiments, like SX, that use an ionic retainer in their stationary phase must provide an additional <retainer> filled with the following sub-sections:

<analytes>

Each analyte of SX experiment is an ion, whose counter ion is the exchanger if injection is performed is the stationary phase, or the displacer counter-ion if injection is performed in the mobile phase. Each analyte is defined in its own sub-section, whose name is the analyte name. Each analyte section has sub-sections:

<interactions>

An interaction corresponds, for a SX simulation, to the association of two or more analytes in the mobile phase. Each ion pair (or cluster) is described in a section whose name is the name of the cluster. Each cluster section has two sub-sections:

The <of> section has as many subsections than analytes in the current cluster. Each analyte sub-section is named after the analyte name declared in the <analytes> section. Finally each analyte sub-section has its <n type="int"> sub-sub-section that indicates the number of times the current analyte is present in the cluster. As example, if cluster I is formed by interaction of analytes S1 and S2 (1 for 1), the correspondant piece of input file is:

     <interactions>
       <I>
         <of>
	   <S1>
	     <n type="int">
	       1
	     </n>
	   </S1>
	   <S2>
	     <n type="int">
	       1
	     </n>
	   </S2>
	 </of>
	 <constant type="real">
	   1000.0
	 </constant>
       </I>
     </interactions>
   

<injection>

In general, the analytes are not injected in a single cell, but occupies a given number of cells. In a SX experiment, injection may be achived either in the stationary or in the mobile phase. The sub-sections in the <injection> section are:

<development>

This section has two sub-sections:

<detection>

displacer Each detector has its own section that is directly identified by its tag. A detector section has two sub_sections:


columnheads.pl

In order to be able to draw graphs from detector output, the user must have the correspondance table between chemical species names and internal variable names. The latter are directly connected with column indexes in detector output. The required information is printed to the standard output of cpcsim and is caught in the log.txt file if the standard output is redirected to it. The command:

    columnheads.pl
   

prints the correspondance table from log.txt by default.

draweffl.pl

draweffl.pl draws what an ideal on-line effluent analyzer would draw during the separation process. It produces an image of the fractogram after each pumping of a volume of stationary phase contained in a single cell.

The draweffl.pl command alone (no argument) uses the file named "default_draweffl_info" as parameter file if there is one in the current directory. A sample default parameter file is located in the "Draw" directory of the CpcSim distribution. The name of a parameter file can be passed as argument to draweffl.pl.

A parameter file contains lines that all follow the syntax:

    parameter = value
   

The blanks at each side of the equal signe are mandatory. No comment line is possible. The possible parameters are:

drawfull.pl

drawfull.pl draws what Foucault et coll. could observe in a so-called Visual CPC, if it were possible to equip it with a chemical analyzer. It produces a view of the full column content after each pumping of a volume of stationary phase contained in a single cell.

The drawfull.pl command alone (no argument) uses the file named "default_drawfull_info" as parameter file if there is one in the current directory. A sample default parameter file is located in the "Draw" directory of the CpcSim distribution. The name of a parameter file can be passed as argument to drawfull.pl.

A parameter file contains lines that all follow the same syntax as draweffl.pl with the same parameters.

comp.pl

The comp.pl command alone (no argument) uses the file named "default_comp_info" as parameter file if there is one in the current directory. A sample default parameter file is located in the "Draw" directory of the CpcSim distribution. The name of a parameter file can be passed as argument to comp.pl.

This program glues side-by-side pairs of images generated by draweffl.pl and drawfull.pl that have identical indexes. The parameter file has the same syntax as draweffl.pl and drawfull.pl. Possible parameters are:

stammer.pl

stammer.pl is used before individual jpeg images are put together to build a MPEG movie. The lowest image rate, 24 images per second, is often too high to be useful. A workaround consists in the duplication of each image. The Perl program, stammer.pl, does this.

The stammer.pl command alone (no argument) uses the file named "default_stammer_info" as parameter file if there is one in the current directory. A sample default parameter file is located in the "Draw" directory of the CpcSim distribution. The name of a parameter file can be passed as argument to stammer.pl.

The parameter file has the same syntax as draweffl.pl, drawfull.pl, and comp.pl. Possible parameters are:


ppmtompeg

ppmtopng is part of the Netpbm software package. ppmtompeg assembles static images to build a MPEG movie. A sample parameter file, genmpeg, is provided in the Bzlkmob directory of the CpcSim distribution. It takes by default jpeg files and glues them in a MPEG-1 movie file, according to the content of the parameter file. The name of the parameter file is passed as argument to the ppmtompeg command (no default file name). If a set of comp*.png files has to be processed, it must (see below) be converted to jpeg files first:

    mogrify -format jpeg comp*.png
   

The comp*.jpeg files can be multiplicated using stammer.pl. It produces 400 mult*.jpeg files from 100 initial jpeg files if factor equals 4 in its parameter file. It seems that ppmtompeg is able to convert "on-the-fly" but I did not have much success trying to do it. The syntax of the parameter file is straightforward. Parameters of interest are:

More details about ppmtompeg parameters with "man ppmtompeg".


Jean-Marc Nuzillard
jm.nuzillard@univ-reims.fr

October 21st 2005