Subject: Shared functions - repeated


   Dear all -
f
   ollowing up on our new good intentions to work on shared
software, I'd like to repeat my propositions from _January_
(sic!) this year for shared detector modeling functions and
on which I cannot find much further discussion. At the time,
the detailed proposal only went to Niels Jørgen and Stefan.

=== repeated message ===

   While the code is commented, I'd like to explain some of my choices
in order to give you a better basis for discussions:

1. Multiple .c files

    While the CTS may hint at something different, many of us have come
    to the conclusion that it is better to have multiple .c files - just
    look at the DAL library source code ...

    I've tried to split the code according to logical boundaries, i.e.
    jemx_shared_imod.c contains function to access and manipulate data
    from the IMOD group, jemx_shared_general.c generic functions etc.
    My hope was that different people within our team could take care of
    different parts in the long run.

2. Detector as a C struct

    I've decided to make the high level interface via a new datatype
    JEMXdetectorData which is a C struct encompassing several areas
    and (currently) one real variable - the area.

    The reasoning behind this is that if (when!) we find further properties
    of the detector we want to hand around, we can simply add another element
    to the definition of the struct. Functions requiring the added information
    can use it without changing their interface, code not requiring it, just
    works as before.

3. Low-level access via simple arrays

    Despite my arguments for the struct above, I've kept the low level access
    with simple data types for two reasons:

    (a) You could possibly use those without adopting the struct.

    (b) I wanted to access the different parts separately but did not want
        to fill the struct piecewise - it should all be set at once.

Both 2 and 3(b) go a bit into the direction of object oriented programming,
which is on purpose - it should help in sharing.

4. No floats, just double

    I've declared all real number data as "double" for the simple reason that
    this should avoid practially all rounding problems one could ever have.
    While this makes the struct large (>2.5 MB) this is no problem on any
machine
    capable of running our code - my new Palm has 64 Mb!

    A lesson, I've taken from a WWW page on numerical methods was:
    "store (on disk) in single, calculate in double, wherever you can".
    The first cuts down access times and avoids storing numerical noise
    if your calculations aren't perfect. The second is the simplest way
    to reduce numerical worries.

    Note that DAL/CFITSIO have absolutely no problem reading single precision
    (or less) into double, if the functions are called correctly. One mistake,
    e.g., Carol Anne is often doing is to adapt her internal arrays exactly to
    the data formats on disk. This is unnecessarily complicated and can lead
    to problems in calculations sometimes. Putting it to the extreme we could
    probably read all integer-type data into arrays of long and all real numbers
    into double.

5. But unsigned int for the DETE-MOD map.

    Here I've deviated from the above - mainly because we do bitwise matching
    with those data and there converting to another type is more tricky.


6. JEMXdetectorCalcOnAxisArea - a fudge

    Originally I had intended to have a function which calculates area and
    the "used pixels map" as function of source position, but found I was
    too lazy to figure out the details. In the long run I would assume that
    this function is replaced by a more generic one.


   So how do we continue from here? Do you like my ideas, do they seem to go
in the right direction? Should I circulate this code further? If things just
went my way we would also define datatypes and functions for the following
elements:

* All the shadowing material - mask, collimator, support structure ...
   (single struct or several, if the latter which?)

* Sources (position in RA/Dec, in COSX/Y/Z, ...)

Stefan and I could also discuss generic functions to write spectra and
lightcurves and what their interface should be.

   Let me know your thoughts,
   Peter