REQUIREMENTS FOR "GOLD" SUPPORT IN MODEL DATABASE
Background
==========
When getting the model (Rmats or Twiss) for a given device through
AIDA, the model server goes through a multi-step search to establish
from which model run to return data.
The present behavior is that: if the RUNID parameter is given,
the model is taken from the specified run. Otherwise, if the MODE
parameter is given, the model returned is the chronologically most
recent of the specified mode; if the MODE parameter is not given, the
model returned is the chronologically most recent mode 5 model of the
device if it is mode 5, and simply the most recent chronologically
uploaded model of any mode otherwise.
The algorithm above is given in summary - it's more involved when the
Rmat from A to B is requested. The algorithm for choosing the run from
which to get the model is summarized in [1], and described at length
in [2].
Problem
=======
Since it's largely the last model to be uploaded, models can't be
uploaded without affecting running physics software and operations, and
therefore it's difficult to experientially test a model, or
temporarily upload one for a given experiment, Energy profile, etc.
Also, the chronologically most recent model of each mode isn't
completely obvious to the eye in the model web page (nor possibly in
the coming Optics application), and the search algorithm is not
completely obvious.
Solution
========
We will support the designation of a single "gold" model of each model
mode (effectively a beamline). Other things being equal then, requests
for model data of devices in a given mode will be taken from the gold
model for that model mode. You would be able to change which is the
gold model through the APEX web page [3], and through Paul and Quan's
new optics GUI.
No changes are required on the client side (no matlab changes), though
users should be aware of the change in behaviour.
See enclosed example screens:
Run Data table showing new GOLD column [4].
Gold History [5].
GOLD and MODE
-------------
Each MODE can be assigned (at most) one EXTANT GOLD model, and one DESIGN GOLD
model, see picture.
NOTE: So golds will not go with beamline per se. Choosing to
associate gold with mode is the choice which makes most sense
if mode is primarily used to identify such things as different
initial conditions or ending energy.
GOLD and DESIGN models
----------------------
We will allow DESIGN models to be designated "gold" too. This is a
consequence of Paul Chu's plan to run and upload an energy scaled
design model every time an energy scaled extant model is uploaded. If
there were no GOLD design model in that case, every time the energy
scaled extant model was run and uploaded, requests for the design
model would get different data to before the model run. It's more
intuitive if design models for a mode are pretty constant.
Note that, if an EXTANT model is made GOLD, it would NOT necessarily
be true that any DESIGN model for taht same mode computed and uploaded
at the same time would become the design GOLD of that mode too. We
would leave the designation of which DESIGN is teh gold design
entirely up to users, just as for extant models.
It's possible for a given mode not to have any model runs designated
gold.
FUNCTIONAL REQUIREMENTS
=======================
This section lists functional requirement changes by subsystem. There
are 4 subsystems involved:
1) AIDA (to change which model from which it gets data)
2) Oracle (to support GOLD in model subschema, and modifications
to oracle procedures)
3) Model upload page (to support setting which model is GOLD, and
history)
4) Model Optics GUI (to support setting which model is GOLD, and
history).
AIDA
====
The AIDA interface for model requests will be modified to add 2 more
permissible values for the RUNID parameter (0 and 1).
RUNID = 0 - means get from the latest model
RUNID = 1 - means get from the gold model
RUNID = nnn - means get from the given numbered model (as now)
RUNID = 0 will be the default. This will preserve the behavior of
existing clients, since presently if RUNID is not given, the latest
model is used.
device [RUNID=0|1|nn] [MODE=mm] [TYPE=DESIGN|EXTANT] [POS=BEG|MID|END]
AIDA's model search algorithm
=============================
(In all of the search criteria below, it's assumed that the type,
"Design" or "Extant", is also a conjunction in the search criteria).
The combinations of RUNID and MODE for which the resulting behavior
must be specified:
1) runid = nn
[mode is ignored]
2) runid = 1 (gold)
mode given
mode not given
3) runid = 0 (latest) - the default
mode given
mode not given
The behavior under each combination above, for both cases of just
getting the model of one device (A), or Rmat from A to B, is given
below:
a) If only a single device's model (A) is required:
---------------------------------------------------
1) If a run ID is given (RUNID>1), then look for the device (A) in the model
identified by the given Run ID. If A is not found in the given Run ID
model, return an error "device not found in run id."
[This is unchanged from before GOLD was added]
2) If Run ID = 1 (GOLD) is given;
2.1) If MODE is given, then return the model parameters from the
gold model of the given mode. If A is not in the gold model of
the given mode, return an error (do not search further).
2.2) If MODE is not given, then;
2.2.1) If A is in the MODE = 5 gold model, then return the
params of A from that model.
2.2.2) If A is NOT in the MODE = 5 gold model, then return
params of A from the gold model with the largest Run ID (that
is, chronologically latest uploaded) that contains A.
3) If Run ID = 0 (LATEST) - the default;
3.1) If MODE is given, then return the model params of A from the
model with the largest run ID of the given MODE that contains
A. If A is not any model matching the given MODE, return an
error like "device not found in MODE".
3.2) If MODE is NOT given, then;
3.2.1) If A is in the MODE = 5 model, then return the params
of A from model largest Run ID whose MODE == 5.
3.2.2) If A is NOT in a MODE = 5 model, then return the params
of A from the model with the largest Run-ID containing
A. This is the present behavior.
b) If the model Rmat A to B is required
---------------------------------------
(In all of the search criteria below, it's assumed that the type,
"Design" or "Extant", is also a conjunction in the search criteria).
1) If a (>1) run ID is given, then look for A and B in the model
identified by that Run ID. If A or B is not found in the model with
the given Run ID, return an error like "device not found in run
id."
2) If Run ID = 1 (GOLD) is given;
2.1) If MODE is given, then return the model parameters computed
from A and B Rmats from the gold model of the given mode. If A
or B is not in the gold model of the given mode, return an
error (do not search further).
2.2) If MODE is not given,
2.2.1) If A & B are in the gold MODE = 5 model, then return
the params computed from A and B from that model.
2.2.2) If A or B is not in the gold MODE 5 model, then return
the params computed form the gold model with largest run
id (chronologically most recent) that contains both A
and B.
3) If Run ID = 0 (LATEST) - the default if RUNID param is not specified
3.1) If MODE is given, then return the model params of A and B from
the model with the largest run-ID that matches the given MODE,
and contains both A and B. If A or B is not in the model with
the largest run ID matching the given MODE, return an error
like "device not found in MODE."
3.2) MODE is NOT given, then
3.2.1) If A & B are in any MODE = 5 model, then return the
Rmat computed from A and B of the model with the
largest Run ID, whose MODE == 5, that contains both
(see note a.).
Note a) For expediency of coding, I'm going to weaken
this requirement to:
3.2.1) Attempt to return Rmats computed from A and B
from the model with the largest Run ID, whose
MODE == 5, that contains A and B. However, if
the largest Run-ID model of MODE = 5 that
contains the downstream device, does not in
fact also contain the upstream device (which of
course it should), then return an error.
3.2.2) If A or B is NOT in a MODE = 5 model, then return the
Rmat computed from A and B from the model with the
largest Run ID that contains both A and B. This is the
present behaviour (see note b).
Note b) For expediency of coding, I'm going to weaken
this requirement to:
3.2.2) If A or B is NOT in a MODE = 5 model, then
return the Rmat computed from A and B from the
model with the largest Run ID containing the
downstream device. This is the present behavior
(see note b).
ORACLE
======
The above functional requirements in the AIDA model data
provider, may be completed with the following addition to the
Oracle MACHINE_MODES sub-schema, and oracle code.
Machine_model sub-schema
------------------------
Add 1 small table, Gold, to Machine_model:
Gold
----
ID (PK)
runs_ID (FK) [The foreign key to Runs table, ID]
Date [The date the runs_ID runid above was made gold]
Comment [User entered comment when setting this gold]
Created_by [The user name of the user who made this model gold]
Oracle Procedures
----------------
Below are the required modifications to Oracle code:
1) GET_MODE_RUNID
Add Gold arg, as 4th arg, taking values 1 or null:
1 = The run found must be a gold run (the present Gold of the
given mode).
null = Run need not be gold
If mode is not given, and Gold = 1, then return the run ID of the model
with the largest run ID which is gold (per a & b 2.2.2 above):
Modification to Aida:
{code}
"Select MACHINE_MODEL.ONLINE_MODEL_PKG.GET_MODE_RUNID("+
"'" + instance +"'," +
(type.equals("NULL") ? "null" : "'"+type+"'") + "," +
(mode.equals("NULL") ? "null" : "'"+mode+"'") +
add line ->> (run == 1 ? 1 : "null") +
") as run_id from dual";
{code}
2) GET_MODE_TWISS_DATA
Expand permitted values of 5th param Run-ID, so that:
null = latest (as now)
1 = gold
> 1 = match to argument (as now)
Curiously, run id param of GET_MODE_TWISS_DATA seems to be char, not
numerical? Why not NUMBER?
Aida code change to users of GET_MODE_TWISS_DATA:
get_twiss: - no change necessary, unless we decide to change run-Id arg to NUMBER.
{code}
"SELECT KINETIC_ENERGY, " +
"PSI_X, BETA_X, ALPHA_X, ETA_X, ETAP_X,"+
"PSI_Y, BETA_Y, ALPHA_Y, ETA_Y, ETAP_Y,"+
"ZPOS, LEFF, SLEFF, ORDINAL FROM "+
"TABLE(MACHINE_MODEL.ONLINE_MODEL_PKG.GET_MODE_TWISS_DATA("+
"'" + q.instance() +"'" +
",'" + posParam +"'" +
"," + (typeParam.equals("NULL") ? "null" :
"'"+typeParam+"'") +
"," + (modeParam.equals("NULL") ? "null" :
"'"+modeParam+"'") +
"," + (runParam.equals("NULL") ? "null" :
"'"+runParam+"'") +
")) T ORDER BY PSI_X";
{code}
runParam interpreted as: null = latest, 1 = is gold, > 1 = match to value
3) GET_MODE_RMATRIX_DATA
Expand permitted values of 5th param RunID, so that:
null = latest (as now)
1 = gold
> 1 = match to argument (as now)
No change required to Aida's call to GET_MODE_RMATRIX_DATA, however,
runParam should now be interpreted as as above:
{code}
"SELECT R11, R12, R13, R14, R15, R16,"+
"R21, R22, R23, R24, R25, R26,"+
"R31, R32, R33, R34, R35, R36,"+
"R41, R42, R43, R44, R45, R46,"+
"R51, R52, R53, R54, R55, R56,"+
"R61, R62, R63, R64, R65, R66 FROM "+
"TABLE(MACHINE_MODEL.ONLINE_MODEL_PKG.GET_MODE_RMATRIX_DATA(" +
"'" + q.instance() +"'," +
"'" + posParam + "',"+
(typeParam.equals("NULL") ?
"null" : "'"+typeParam+"'") + "," +
(modeParam.equals("NULL") ?
"null" : "'"+modeParam+"'") + "," +
(runIdParam.equals("NULL") ?
"null" : "'"+runIdParam+"'") +
")) T";
{code}
Model GUIs and APEX Reports
===========================
The following requirements apply to both the Model Optics GUI and to
the online Model upload and viewing web page [3].
Table of all Runs:
-----------------
The table of model runs should be modified to include a new column
showing which model runs are gold. See example in [4] enclosed:
Designate which model is GOLD:
------------------------------
You must be able to designate which run of each mode is to be the gold
of that mode. This is separately assignable for each of extant and
design.
This should be done easily from the same screen as the Golds panel
below.
Golds Screen: Display golds history and setting gold:
-----------------------------------------------------
You will be able to see a history of which models have
previously been gold, as well as which is the present gold, of each
mode. See example in [5] enclosed.
[1] LCLS Model Data Provider Guide,
http://www.slac.stanford.edu/grp/cd/soft/aida/lclsModelDpGuide.html
[2] "MODE" handling requirements, http://tinyurl.com/da4fy9
[3] Model upload and viewing web page,
https://oraweb.slac.stanford.edu/apex/slacprod/f?p=400
[4] Example Run Data table, as in APEX and the Model GUI
gold_example_run_data.pdf
[5] Example Gold History, as would be included in the model upload APEX application [3] and Paul's new Model GUI:
gold_example_gold_report.pdf