"Fossies" - the Fresh Open Source Software Archive

Member "gnuastro-0.9/lib/gnuastro/data.h" (2 Jan 2019, 11745 Bytes) of package /linux/privat/gnuastro-0.9.tar.lz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "data.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 0.8_vs_0.9.

    1 /*********************************************************************
    2 data -- Structure and functions to represent/work with data
    3 This is part of GNU Astronomy Utilities (Gnuastro) package.
    4 
    5 Original author:
    6      Mohammad Akhlaghi <mohammad@akhlaghi.org>
    7 Contributing author(s):
    8 Copyright (C) 2015-2019, Free Software Foundation, Inc.
    9 
   10 Gnuastro is free software: you can redistribute it and/or modify it
   11 under the terms of the GNU General Public License as published by the
   12 Free Software Foundation, either version 3 of the License, or (at your
   13 option) any later version.
   14 
   15 Gnuastro is distributed in the hope that it will be useful, but
   16 WITHOUT ANY WARRANTY; without even the implied warranty of
   17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   18 General Public License for more details.
   19 
   20 You should have received a copy of the GNU General Public License
   21 along with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
   22 **********************************************************************/
   23 #ifndef __GAL_DATA_H__
   24 #define __GAL_DATA_H__
   25 
   26 /* Include other headers if necessary here. Note that other header files
   27    must be included before the C++ preparations below */
   28 #include <math.h>
   29 #include <wcslib/wcs.h>
   30 
   31 /* When we are within Gnuastro's building process, `IN_GNUASTRO_BUILD' is
   32    defined. In the build process, installation information (in particular
   33    the `restrict' replacement) is kept in `config.h' (top source
   34    directory). When building a user's programs, this information is kept in
   35    `gnuastro/config.h'. Note that all `.c' files in Gnuastro's source must
   36    start with the inclusion of `config.h' and that `gnuastro/config.h' is
   37    only created at installation time (not present during the building of
   38    Gnuastro). */
   39 #ifndef IN_GNUASTRO_BUILD
   40 #include <gnuastro/config.h>
   41 #endif
   42 
   43 #include <gnuastro/type.h>
   44 
   45 
   46 
   47 /* C++ Preparations */
   48 #undef __BEGIN_C_DECLS
   49 #undef __END_C_DECLS
   50 #ifdef __cplusplus
   51 # define __BEGIN_C_DECLS extern "C" {
   52 # define __END_C_DECLS }
   53 #else
   54 # define __BEGIN_C_DECLS                /* empty */
   55 # define __END_C_DECLS                  /* empty */
   56 #endif
   57 /* End of C++ preparations */
   58 
   59 
   60 
   61 /* Actual header contants (the above were for the Pre-processor). */
   62 __BEGIN_C_DECLS  /* From C++ preparations */
   63 
   64 
   65 
   66 
   67 
   68 /* Flag values for the dataset. Note that these are bit-values, so to be
   69    more clear, we'll use hexadecimal notation: `0x1' (=1), `0x2' (=2),
   70    `0x4' (=4), `0x8' (=8), `0x10' (=16), `0x20' (=32) and so on. */
   71 
   72 /* Number of bytes in the unsigned integer hosting the bit-flags (`flag'
   73    element) of `gal_data_t'. */
   74 #define GAL_DATA_FLAG_SIZE         1
   75 
   76 /* Bit 0: The has-blank flag has been checked, so a flag value of 0 for the
   77           blank flag is trustable. This can be very useful to avoid
   78           repetative checks when the necessary value of the bit is 0. */
   79 #define GAL_DATA_FLAG_BLANK_CH     0x1
   80 
   81 /* Bit 1: Dataset contains blank values. */
   82 #define GAL_DATA_FLAG_HASBLANK     0x2
   83 
   84 /* Bit 2: Sorted flags have been checked, see GAL_DATA_FLAG_BLANK_CH. */
   85 #define GAL_DATA_FLAG_SORT_CH      0x4
   86 
   87 /* Bit 3: Dataset is sorted and increasing. */
   88 #define GAL_DATA_FLAG_SORTED_I     0x8
   89 
   90 /* Bit 4: Dataset is sorted and decreasing. */
   91 #define GAL_DATA_FLAG_SORTED_D     0x10
   92 
   93 /* Maximum internal flag value. Higher-level flags can be defined with the
   94    bitwise shift operators on this value to define internal flags for
   95    libraries/programs that depend on Gnuastro without causing any possible
   96    conflict with the internal flags or having to check the values manually
   97    on every release. */
   98 #define GAL_DATA_FLAG_MAXFLAG      GAL_DATA_FLAG_SORTED_D
   99 
  100 
  101 
  102 
  103 /* Main data structure.
  104 
  105    mmap (keep data outside of RAM)
  106    -------------------------------
  107 
  108      `mmap' is C's facility to keep the data on the HDD/SSD instead of
  109      inside the RAM. This can be very useful for large data sets which can
  110      be very memory intensive. Ofcourse, the speed of operation greatly
  111      decreases when defining not using RAM, but that is worth it because
  112      increasing RAM might not be possible. So in `gal_data_t' when the size
  113      of the requested array (in bytes) is larger than a certain minimum
  114      size (in bytes), Gnuastro won't write the array in memory but on
  115      non-volatile memory (like HDDs and SSDs) as a file in the
  116      `./.gnuastro' directory of the directory it was run from.
  117 
  118          - If mmapname==NULL, then the array is allocated (using malloc, in
  119            the RAM), otherwise its is mmap'd (is actually a file on the
  120            ssd/hdd).
  121 
  122          - minmapsize is stored in the data structure to allow any
  123            derivative data structures to follow the same number and decide
  124            if they should be mmap'd or allocated.
  125 
  126          - `minmapsize' ==  0: array is definitely mmap'd.
  127 
  128          - `minmapsize' == -1: array is definitely in RAM.
  129 
  130 
  131    block (work with only a subset of the data)
  132    -------------------------------------------
  133 
  134      In many contexts, it is desirable to slice the data set into subsets
  135      or tiles, not necessarily overlapping. In such a way that you can work
  136      on each independently. One option is to copy that region to a separate
  137      allocated space, but in many contexts this isn't necessary and infact
  138      can be a big burden on CPU/Memory usage. The `block' pointer in
  139      `gal_data_t' is defined for situations where allocation is not
  140      necessary: you just want to read the data or write to it
  141      independently, or in coordination with, other regions of the
  142      dataset. Added with parallel processing, this can greatly improve the
  143      time/memory consumption.
  144 
  145      See the figure below for example: assume the larger box is a
  146      contiguous block of memory that you are interpretting as a 2D
  147      array. But you only want to work on the region marked by the smaller
  148      box.
  149 
  150                     tile->block = larger
  151                 ---------------------------
  152                 |                         |
  153                 |           tile          |
  154                 |        ----------       |
  155                 |        |        |       |
  156                 |        |_       |       |
  157                 |        |*|      |       |
  158                 |        ----------       |
  159                 |_                        |
  160                 |*|                       |
  161                 ---------------------------
  162 
  163      To use `gal_data_t's block concept, you allocate a `gal_data_t *tile'
  164      which is initialized with the pointer to the first element in the
  165      sub-array (as its `array' argument). Note that this is not necessarily
  166      the first element in the larger array. You can set the size of the
  167      tile along with the initialization as you please. Recall that, when
  168      given a non-NULL pointer as `array', `gal_data_initialize' (and thus
  169      `gal_data_alloc') do not allocate any space and just uses the given
  170      pointer for the new `array' element of the `gal_data_t'. So your
  171      `tile' data structure will not be pointing to a separately allocated
  172      space.
  173 
  174      After the allocation is done, you just point `tile->block' to the
  175      `gal_data_t' which hosts the larger array. Afterwards, the programs
  176      that take in the `sub' array can check the `block' pointer to see how
  177      to deal with dimensions and increments (strides) while working on the
  178      `sub' datastructure. For example to increment along the vertical
  179      dimension, the program must look at index i+W (where `W' is the width
  180      of the larger array, not the tile).
  181 
  182      Since the block structure is defined as a pointer, arbitrary levels of
  183      tesselation/griding are possible. Therefore, just like a linked list,
  184      it is important to have the `block' pointer of the largest dataset set
  185      to NULL. Normally, you won't have to worry about this, because
  186      `gal_data_initialize' (and thus `gal_data_alloc') will set it to NULL
  187      by default (just remember not to change it). You can then only change
  188      the `block' element for the tiles you define over the allocated space.
  189 
  190      In Gnuastro, there is a separate library for tiling operations called
  191      `tile.h', see the functions there for tools to effectively use this
  192      feature. This approach to dealing with parts of a larger block was
  193      inspired from the way the GNU Scientific Library does it in the
  194      "Vectors and Matrices" chapter.
  195 */
  196 typedef struct gal_data_t
  197 {
  198   /* Basic information on array of data. */
  199   void     *restrict array;  /* Array keeping data elements.               */
  200   uint8_t             type;  /* Type of data (see `gnuastro/type.h').      */
  201   size_t              ndim;  /* Number of dimensions in the array.         */
  202   size_t            *dsize;  /* Size of array along each dimension.        */
  203   size_t              size;  /* Total number of data-elements.             */
  204   char           *mmapname;  /* File name of the mmap.                     */
  205   size_t        minmapsize;  /* Minimum number of bytes to mmap the array. */
  206 
  207   /* WCS information. */
  208   int                 nwcs;  /* for WCSLIB: no. coord. representations.    */
  209   struct wcsprm       *wcs;  /* WCS information for this dataset.          */
  210 
  211   /* Content descriptions. */
  212   uint8_t             flag;  /* Flags: currently 8-bits are enough.        */
  213   int               status;  /* Context specific value for the dataset.    */
  214   char               *name;  /* e.g., EXTNAME, or column, or keyword.      */
  215   char               *unit;  /* Units of the data.                         */
  216   char            *comment;  /* A more detailed description of the data.   */
  217 
  218   /* For printing */
  219   int             disp_fmt;  /* See `gal_table_diplay_formats'.            */
  220   int           disp_width;  /* Width of space to print in ASCII.          */
  221   int       disp_precision;  /* Precision to print in ASCII.               */
  222 
  223   /* Pointers to other data structures. */
  224   struct gal_data_t  *next;  /* To use it as a linked list if necessary.   */
  225   struct gal_data_t *block;  /* `gal_data_t' of hosting block, see above.  */
  226 } gal_data_t;
  227 
  228 
  229 
  230 
  231 
  232 /*********************************************************************/
  233 /*************              allocation             *******************/
  234 /*********************************************************************/
  235 gal_data_t *
  236 gal_data_alloc(void *array, uint8_t type, size_t ndim, size_t *dsize,
  237                struct wcsprm *wcs, int clear, size_t minmapsize,
  238                char *name, char *unit, char *comment);
  239 
  240 void
  241 gal_data_initialize(gal_data_t *data, void *array, uint8_t type, size_t ndim,
  242                     size_t *dsize, struct wcsprm *wcs, int clear,
  243                     size_t minmapsize, char *name, char *unit, char *comment);
  244 
  245 void
  246 gal_data_free_contents(gal_data_t *data);
  247 
  248 void
  249 gal_data_free(gal_data_t *data);
  250 
  251 
  252 
  253 
  254 
  255 /*********************************************************************/
  256 /*************        Array of data structures      ******************/
  257 /*********************************************************************/
  258 gal_data_t *
  259 gal_data_array_calloc(size_t size);
  260 
  261 void
  262 gal_data_array_free(gal_data_t *dataarr, size_t num, int free_array);
  263 
  264 
  265 
  266 
  267 
  268 /*************************************************************
  269  **************            Copying             ***************
  270  *************************************************************/
  271 gal_data_t *
  272 gal_data_copy(gal_data_t *in);
  273 
  274 gal_data_t *
  275 gal_data_copy_to_new_type(gal_data_t *in, uint8_t newtype);
  276 
  277 gal_data_t *
  278 gal_data_copy_to_new_type_free(gal_data_t *in, uint8_t newtype);
  279 
  280 void
  281 gal_data_copy_to_allocated(gal_data_t *in, gal_data_t *out);
  282 
  283 gal_data_t *
  284 gal_data_copy_string_to_number(char *string);
  285 
  286 
  287 __END_C_DECLS    /* From C++ preparations */
  288 
  289 #endif           /* __GAL_DATA_H__ */