LITpro is divided in modules each with its own purpose. NAMING CONVENTIONS ------------------ To avoid namespace conflicts, each module has its own prefix (e.g. "oiw" for the world manager). The names of the public functions provided by a given module start with the prefix in lowercase letters followed by an underscore (e.g. "lpw_foo"). The names of public variables start with the prefix in uppercase letters followed by an underscore (e.g. "LPW_DATA"). The names of private functions and private variables follow the same rules but have an underscore prepended (e.g. "_lpw_bar" is a private function, "_LPW_CACHE" is a private variable/symbol). --------------------------------------------------------------------------- LITpro_world.i - purpose: Implementation of routines to manage the "world". prefix: lpw_ lpw_delete_parameter(world, name) lpw_get_parameter(world, name) lpw_get_workspace(world, pkg) lpw_list_of_parameters(world) lpw_new_world(nil) lpw_set_parameter(world, name, units=, value=, vmin=, vmax=) --------------------------------------------------------------------------- LITpro_parser.i - purpose: Implementation of parser routines for the building block model. prefix: lpm_ ----------------------------------------------- Layout of the hash table returned by the parser ----------------------------------------------- Rules for the naming of the members of the hash table : lowercase - predefined name of a member. Appears as is in the hash table. TGT1 - computed name of a member. The name is chosen by the software in order to be unique in the hash table. "NAME" - name of a member given by the user. "MODEL" | +-- target | | | +-- TGT1 [1] | | | | | +-- ident (string) Target name (identifier) in data files. | | +-- files (string array) list of data files for this target. | | +-- nobj (long) number of functions for the object. | | +-- objlist (string array) list of the function names. | | | | | +-- OBJ1 [2] | | | | | | | +-- function (string) name of a function. | | | `-- param | | | | | | | +-- PAR1 (string) [3] | | | | | | | [...] | | | | | | [...] `-- PARn (string) [3] | | | | | +-- OBJn [2] | | | | | | | +-- function (string) name of a function. | | | `-- param | | | | | | | +-- PAR1 (string) [3] | | | | | | | [...] | | | | | | | `-- PARn (string) [3] | | | | | +-- instrument Reserved for latter use ;-). | | | | | | | +-- function (string) name of a function. | | | `-- param | | | | | | | +-- PAR1 (string) [3] | | | | | | | [...] | | | | | | | `-- PARn (string) [3] | | | | | +-- transforms | | | | | | | +-- anamorphosis | | | +-- rotation | | | +-- translation | | | `-- expansion | | | | | `-- residuals | | | | | +-- VIS (string) function for residuals from VIS | | +-- VIS2 (string) function for residuals from VIS2 | | +-- T3 (string) function for residuals from T3 | [...] `-- NORMALIZE (string) function for residuals. | | | `-- TGTn [1] Hash table for a new target entry. | | | [...] | +-- param Sets any parameter defined in target hash table. | | | +-- "NAME1" [4] Name of the parameter, chosen by the user. | | | | | +-- descr (string) Informative string for this parameter. | | +-- fixed (long) TRUE/FALSE. To be fit or not to be fit... | | +-- scale (double) parameter typical order of magnitude. | | +-- units (string) Units (only informative). | | +-- value (double) Starting value. | | +-- vmin (double) Lowest allowed value. | | `-- vmax (double) Largest allowed value. | [...] | | | `-- "NAMEn" | | | [...] same members for all the parameters. | `-- fitter (string) name of the fitting method. [1] - For a target, the key is computed and cannot be the ident itself. Indeed, this would prevent us to use the same ident for two different targets. For instance, it could be necessary to define two different models for two different sets of data. The models could be closely related through the naming of the parameters. [2] - Here again, the naming is computed because for modelling one target, we can use the same function (same name) several times with different parameters. [3] - The name of each key PAR# is equal to the exact name of one of the parameters of this particular function. Its contents is the name chosen by the user for this parameter, which must appear as a key in the param hash table. [4] - The keys are the names chosen by the user for the parameters. A name is unique and can appears several times anywhere, in several functions. --------------------------------------------------------------------------- LITpro_modeler.i - purpose: Implementation of modeler routines for the building block model. prefix: lpm_ provides: lpm_load_model(filename) - loads a new model form FILENAME, returns a 'world' opaque object lpm_compute_residuals(world) - returns weighted residuals --------------------------------------------------------------------------- LITpro_fitter.i - purpose: Implementation of fitter routines. prefix: lpf_ --------------------------------------------------------------------------- LITpro_basic.i - -- public doc -- The names of the available of the building-block functions. -- private doc -- The caller (a codger like wrapper) hide 'world' and modeler workspace in variables _LPB_WORLD and _LPB_WORKSPACE (specific to this part of the model, i.e. should be a children of the modeler own workspace). For intance: func _lpb_codger_PARTNAME(world, job) { /* recover current values of all parameters involved in this part of the model */ A1 = lpw_get_parameter(world, "A1").value; A2 = lpw_get_parameter(world, "A2").value; R1 = lpw_get_parameter(world, "R1").value; FWHM = lpw_get_parameter(world, "FWHM").value; A3 = lpw_get_parameter(world, "A3").value; /* setup variables to share 'world' and the workspace for the current part of the model with user-defined functions */ _LPB_WORLD = world; _LPB_WORKSPACE = lpw_get_workspace(world, "modeler").PARTNAME; return (USER_FUNC1(A1, R1) + USER_FUNC2(A2, FWHM) + USER_FUNC3(A3, R1, FWHM)); } where it is assumed that PARTNAME has 3 building blocks (USER_FUNC1, USER_FUNC2 and USER_FUNC3) and depends on 4 parameters (A1, A2, FWHM and A3). Note that there is exactly one PARTNAME per target. Building-block functions are considered as plugins. They need to have access to coordinates (uv frequencies, wavelengths, etc) and let the software to know their parameters. This exchange is done automatically by the codger by a naming the arguments. - The names of the usable arguments to access the coordinates are fixed this way : wavelength - wavelength(s) for the current target as a scalar (monochromatic case) or a NCHN vector (NCHN is the number of spectral channels). Wavelengths are in meters (same as oi-data standard). bandwidth - Effective bandwidh(s) corresponding to the NCHN wavelength vector. Same organisation and same units as for wavelength. ufreq - Spatial frequencies along U for the current target, as a NBAS-by-NCHN array (or NBAS vector for monochromatic data) where NBAS is the number of baselines. Unit is 1/rad. vfreq - Spatial frequencies along V for the current target, as a NBAS-by-NCHN array (or NBAS vector for monochromatic data) where NBAS is the number of baselines. Unit is 1/rad. time - UTC times of data (seconds) as an NBAS vector. Same as oi-data standard. mjd - Modified Julian Days of data as an NBAS vector. Same as oi-data standard. fjd - Fractionnal Modified Julian Days of data as an NBAS vector. This is an add from oi-data standard. This allows the user to have access to an absolute time (merge of mjd and time) through a single variable with an accuracy of 1e-4 second for today. - The names of the arguments for the parameters of a building-block function is known by the software just from the definition of the function itself. The software remember the names of the arguments and their order of appearance. Units: - wavelengths are in meters (same as oi-data standard) - x, y, are in milliarcseconds (not defined in oi-data standard) - u, v, are in 1/rad. This is a departure from oi-data standard where u, v are in meters. Here, baseline vectors are divided by wavelengths (then, meters/meters). - time is in seconds. Example of a building-block function: func USER_FUNC_SAMPLE(ufreq, vfreq, weight, x, y, radius) { phase = -2.*pi*(x*ufreq + y*vfreq); return (weight*J1(abs(ufreq, vfreq)/radius)*(cos(phase) + 1i*sin(phase))); } Arguments can be given in any order. For instance, if you find this more understandable : func USER_FUNC_SAMPLE(vfreq, y, radius, weight, x, ufreq, y) { phase = -2.*pi*(x*ufreq + y*vfreq); return (weight*J1(abs(ufreq, vfreq)/radius)*(cos(phase) + 1i*sin(phase))); } ---------------------------------------------------------------------------