Y123.EXE and OPT123.EXE - supplementary software for the paper
"Simultaneous assessment of the YBa2Cu3O6+z thermodynamics under the
linear error model" by E.B. Rudnyi, V.V. Kuzmenko, and G.F. Voronin
presented at Forth Electronic Computational Chemistry Conference,
http://hackberry.chem.niu.edu/ECCC4/, November 1997.

E.B. Rudnyi
Department of Chemistry
Moscow State University
119899 Moscow, Russia
e-mail RUDNYI@COMP.CHEM.MSU.SU
http://www.chem.msu.su/~rudnyi/welcome.html

(C) 1997, All rights reserved

Requirements: A computer with Windows 95 or Windows NT. You are supposed
              to be familiar with Command Prompt because both programs
              are working from the command line only. Sorry for
              inconvenience.

Files

  Y123.EXE    program to compute thermodynamics properties of the Y123
              phase
  OPT123.EXE  program to estimate unknown parameters in the Gibbs energy
              of Y123 phase from experimental values
  ALL.DAT     database of experimental values for the Y123 phase
  ML.SET      hypotheses for solution ML
  WLS.SET     hypotheses for solution WLS
  ML.MOD      Gibbs energy of Y123 for solution ML
  FIX.MOD     Gibbs energy of Y123 for the solution obtained by
              93DEG/VOR
  WLS.MOD     Gibbs energy of Y123 for solution WLS
  Y123.MOD    the same as ML.MOD. This file is required for both Y123
              and OPT123
  FIX.LST     OPT123 listing for the solution obtained by 93DEG/VOR
  ML.LST      OPT123 listing for solution ML
  WLS.LST     OPT123 listing for solution WLS
  README.TXT  this file

LICENSE

This program is freeware (public domain). Feel free to use and
distribute it, provided no charge is taken. Let me know if you find any
bug. I would also appreciate your comments.

Disclaimer of warranty:

This program is supplied as is. I disclaim all warranties, express or
implied, including, without limitation, the warranties of
merchantability and of fitness of this program for any purpose. I
assume no liability for damages direct or consequential, which may
result from the use of this program.


1. Y123.EXE

This program computes thermodynamics properties of the Y123 phase

  x - the order parameter
  Cpz - heat capacity in J/K/mol
  S - entropy in J/K/mol
  H - H298 - change in enthalpy in kJ/mol
  Del_ox_H - enthalpy of formation from oxides (Eq. 3 in the paper)
  ln{pO2/po} - oxygen partial pressure over Y123

based on the parameters of the Gibbs energy taken from file Y123.MOD.
From the start this file contains the values for our recommended
solution, ML, however you can rewrite it. For example

  copy FIX.MOD Y123.MOD

After this Y123 will compute thermodynamic properties for the solution
obtained by 93DEG/VOR. Thus, while computing thermodynamic properties
pay attention to what is written in file Y123.MOD.

The program can compute the thermodynamic properties of the Y123 phase
either at constant index z

  Y123 -T z_value T_min T_max T_step

or at constant T

  Y123 -z T_value z_min z_max z_step

For example, the next command

  Y123 -T .5 300 1300 100

will produce thermodynamic properties for the composition with z = 0.5
from 300 K to 1300 K.


2. OPT123.EXE

This program is much more complicated than Y123.EXE. It was the
main computational engine in our project.

OPT123.EXE takes file Y123.MOD as the description of the model and also
as the source for the initial values of unknown parameters. Then it
reads two files, a file with experimental values (data_file) and a file
with expert hypotheses (expert_file), maximizes the likelihood function
and writes the output to the listing.

The basic format of the command is

  OPT123 data_file[.dat] expert_file[.set]

There are some options, the list of options can be produced by the
command without parameters

  OPT123

For example, after the command

  OPT123 all ml -otest

the model will be read from Y123.MOD, the experimental values are from
ALL.DAT, the hypotheses are from ML.SET. The results will be written to
file TEST.LST. Without the option -o, the results would be written to
file ML.LST and as the result they would overwrite file ML.LST supplied
by me. The results, file TEST.LST, should be quite close to my file
ML.LST. If this is not the case, then something went wrong.

Command

  OPT123 all wls -otest2

should produce listing that should be close to my WLS.LST.

So, what you can do with OPT123. First, you can add new experimental
values to file ALL.DAT and see what happens. If you do have new
experimental values for the Y123 phase, please also let me know. I would
appreciate this. Note that after adding new experimental values to
ALL.DAT, some modification should be made to the file with hypotheses,
otherwise you may receive useless results.

Second, you can change the hypotheses and obtain new values of
parameters under your own hypotheses. To this end, you have got to write
you own expert_file (you can take as a background either ML.SET or
WLS.SET). However, before this I would recommend you to read the paper
first.

2.1. Format of data_file

This file is written in the free format. White space is recognized as
the word delimiter. The file consists from experiments separated by
semicolon. Each experiment comprises following fields separated by
commas

experiment_ID,
equation_ID,
variables_names,
point1,
point2,
...;

     experiment_ID -   this is any identifier (list of symbols
                       without space, comma or semicolon).

     equation_ID   -   predefined identifier (see ALL.DAT for what can
                       be written here)

     variables_names - two or more identifiers separated by space.
                       Their quantity determines the total number of
                       values in each point. The identifiers
                       themselves are not employed by the program.

     point1        -   two or more values separated by space. The
                       number of values to read is equal to the
                       number of names of variables.

If there are a few words in the fields experiment_ID or equation_ID, the
first only is taken and all the others are ignored. If there are more
values in the field pointN than the number of the names of variables,
the extra values are ignored. If the number of values is less than that,
absent are initialized by zeros. Such rules permit you to write
comments in the fields experiment_ID, equation_ID and pointN.

You can exclude either an experiment or a point from processing. To
exclude a series - put symbol * before the name of the experiment, to
exclude a point - put symbol * in the beginning of the field pointN. You
also can exclude an experiment in expert_file.

2.2. Format of expert_file

If expert_file is absent, OPT123 LINEAR makes calculation with default
hypotheses - all the series are assumed to have the same reproducibility
variances sr_i2 = sr_2 and the same quantities ga_i = ga and gb_i = gb.
In the case of Y123 it is completely useless.

Expert_file is written in the free format and contains the
descriptions of the experiments and the description START. These
descriptions must be finished by semicolon.

OPT123 reads an experiment description, modifies the hypotheses
accordingly and continues reading the next description. When the
description START appears, the utility starts the calculation.

The format of an experiment description is

[*] experiment_ID, hyp_fl sri, hyp_fl sga, hyp_fl sgb;

  * -        this symbol, if present, means that the experiment will be
             ignored.

  experiment_ID - the name of the experiment. All the words after the
             first will be ignored until comma.

  hyp_fl -   the hypothesis flag - one of three characters #, % or *.
             See below.

  sri -      the initial value of the standard deviation of
             reproducibility.

  sga -      the initial value of sqrt(ga_i).

  sgb -      the initial value of sqrt(gb_i).


Character % shows that this variance component will be assumed as an
individual unknown.

Character * makes the variance component constant - it won't be changed
in the maximization procedure.

Character # means that the values of this variance component should be
the same as in the like group shown by subsequent number (0 <= i <= 19).
The groups for sri, sga and sgb are assumed to be different.

For example, next lines

  ex1, #2 1, %  0  , *  1;
  ex2, #2 1, #3 0.5, #3 0;
  ex3, #4 2, #3 0.5, #3 0;
  ex4, #4 2, #3 0.5, %  0;

describe that we have 6 unknown variance components

  1) sr1 = sr2
  2) sr3 = sr4
  3) sga1
  4) sga2 = sga3 = sga4
  5) sgb2 = sgb3
  6) sgb4

sgb1 is assumed to be constant.



2.3. Listing

Listing is self-descriptive. If you have any question, please contact
me.


