Merge branch 'add_file_description' into 'master'

Write file description

See merge request !24

README.md

 # CSDS Reader
 
-The Continuous Simulation Data Stream is a new output system for SWIFT designed to replace the snapshots in simulation using gravity. This is a submodule of SWIFT containing only the reader.
+The Continuous Simulation Data Stream is a new output system for SWIFT designed to replace the snapshots in simulation using gravity.
\ No newline at end of file
+This is a submodule of SWIFT containing only the reader.
+
+
+# File Description
+
+This description corresponds to the CSDS version 1.4.
+If this file is not up to date, please look at the following file ``src/csds_header.c``
+and the function ``header_read``.
+Except from the header, the file consists in a long list of records (see next section).
+In order to differentiate the records, a mask is present in the record's header.
+They are defined within the logfile's header and their value is given by `1 << i`
+where i is the index according to the order given in the header.
+The two first masks are always reserved, in the order,
+for the special flags (e.g. deletion / creation of particles)
+and the timestamp (time information).
+The special flag has a size of 4 bytes.
+The first contains the special flag, the next two some related data and finally
+the particle type.
+The timestamp consists in a `long long` (`integertime_t` in SWIFT)
+and a `double` (time or scale factor).
+
+A few variables needs to be defined first:
+ - `STRING_SIZE` set to 200. This variable is used for all the strings within the library and the file format name.
+ - `CSDS_OFFSET_SIZE` set to 6. This variable provides the number of bytes to use for any offset within the file.
+ - `CSDS_MASK_SIZE` set to 2. This variables provides the number of bytes to use for the masks in the records.
+ - `swift_type_count` set to 7. This variable contains the number of particle types available in SWIFT.
+ 
+
+The structure of the file is the following one:
+ - The file format: "SWIFT_CSDS" (string of `STRING_SIZE` `char`)
+ - Major version number (`int`)
+ - Minor version number (`int`)
+ - Offset direction (`int`). This should be backward (`0`) after a simulation.
+ - Offset to the first record (`unsigned int` with a size of `CSDS_OFFSET_SIZE` bytes). This value provides directly the position of the first record from the beginning of the file.
+ - The length of the strings in the logfile (`unsigned int`): `string_length`
+ - The number of masks available (`unsigned int`).
+ - For each mask:
+   - The name of the mask (string of `string_length` `char`)
+   - Size of the mask in bytes (`unsigned int`)
+ - Read the number of fields per particle type (`swift_type_count` `int`): `number_fields`.
+ - For each particle type:
+   - The order of the fields (`number_fields` `int`). The values correspond to the index within the mask read previously.
+ - A list of masks
+
+# Record Description
+
+Each record has the following structure:
+ - The mask (`CSDS_MASK_SIZE` bytes). This describes the data contained in the tail of the record.
+ - The offset (`CSDS_OFFSET_SIZE` bytes). The distance in the file to the next (previous) corresponding record (depending on the offset direction in the logfile header).
+ - The data (variable size). Each field is given according to the particle type, the order of the fields and the mask in the logfile's header.

src/csds_header.c

@@ -150,12 +150,12 @@ void header_read(struct header *h, struct csds_logfile *log) {
       csds_loader_io_read_data(map, CSDS_OFFSET_SIZE, &h->offset_first_record);
 
   /* Read the size of the strings. */
-  h->string_length = 0;
-  map = csds_loader_io_read_data(map, sizeof(unsigned int), &h->string_length);
+  unsigned int string_length = 0;
+  map = csds_loader_io_read_data(map, sizeof(unsigned int), &string_length);
 
   /* Check if value defined in this file is large enough. */
-  if (STRING_SIZE < h->string_length) {
-    error_python("Name too large in log file %i.", h->string_length);
+  if (STRING_SIZE < string_length) {
+    error_python("Name too large in log file %i.", string_length);
   }
 
   /* Read the number of masks. */
@@ -171,7 +171,7 @@ void header_read(struct header *h, struct csds_logfile *log) {
   /* Loop over all masks. */
   for (unsigned int i = 0; i < masks_count; i++) {
     /* Read the mask name. */
-    map = csds_loader_io_read_data(map, h->string_length, masks[i].name);
+    map = csds_loader_io_read_data(map, string_length, masks[i].name);
 
     /* Set the mask value. */
     masks[i].mask = 1 << i;

src/csds_header.h

@@ -69,9 +69,6 @@ struct header {
   /* Offset of the first record. */
   size_t offset_first_record;
 
-  /* Number of bytes for strings. */
-  unsigned int string_length;
-
   /* Direction of the offset in the records. */
   enum csds_offset_direction offset_direction;