8.0
general documentation
Loading...
Searching...
No Matches
cs_io.h
Go to the documentation of this file.
1#ifndef __CS_IO_H__
2#define __CS_IO_H__
3
4/*============================================================================
5 * Low level file I/O utility functions for Preprocessor and restart files
6 *============================================================================*/
7
8/*
9 This file is part of code_saturne, a general-purpose CFD tool.
10
11 Copyright (C) 1998-2023 EDF S.A.
12
13 This program is free software; you can redistribute it and/or modify it under
14 the terms of the GNU General Public License as published by the Free Software
15 Foundation; either version 2 of the License, or (at your option) any later
16 version.
17
18 This program is distributed in the hope that it will be useful, but WITHOUT
19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21 details.
22
23 You should have received a copy of the GNU General Public License along with
24 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25 Street, Fifth Floor, Boston, MA 02110-1301, USA.
26*/
27
28/*----------------------------------------------------------------------------*/
29
30#include "cs_defs.h"
31
32/*----------------------------------------------------------------------------
33 * Local headers
34 *----------------------------------------------------------------------------*/
35
36#include "cs_base.h"
37#include "cs_file.h"
38
39/*----------------------------------------------------------------------------*/
40
42
43/*=============================================================================
44 * Local Macro Definitions
45 *============================================================================*/
46
47#define CS_IO_NAME_LEN 32 /* Section header name length */
48
49#define CS_IO_ECHO_NONE -2 /* No verbosity at all */
50#define CS_IO_ECHO_OPEN_CLOSE -1 /* Echo open or close operations */
51#define CS_IO_ECHO_HEADERS 0 /* Echo headers */
52
53/*============================================================================
54 * Type definitions
55 *============================================================================*/
56
57/* Input or output mode */
58
65
66/* Structure associated with opaque pre-processing structure object */
67
68typedef struct _cs_io_t cs_io_t;
69
70/* Structure used to save section header data, so as to simplify
71 passing this data to various functions */
72
73typedef struct {
74
75 const char *sec_name; /* Pointer to section name */
76 cs_file_off_t n_vals; /* Number of associated values */
77 size_t location_id; /* Id of associated location, or 0 */
78 size_t index_id; /* Id of associated index, or 0 */
79 size_t n_location_vals; /* Number of values per location */
80 cs_datatype_t elt_type; /* Type if n_elts > 0 */
81 cs_datatype_t type_read; /* Type in file */
82
84
85/*=============================================================================
86 * Global variables
87 *============================================================================*/
88
89/* Default hints for files using this API (for MPI-IO) */
90
91extern int cs_glob_io_hints;
92
93/*============================================================================
94 * Public function prototypes
95 *============================================================================*/
96
97/*----------------------------------------------------------------------------
98 * Initialize a kernel IO file structure.
99 *
100 * The magic string may be NULL only in read mode;
101 *
102 * If the position of section bodies is already known (after initial
103 * analysis for example), the file may be opened for reading section bodies
104 * only by using "seek_read_section_bodies_only" as a magic string. This may
105 * be used to map another type of file to kernel io files, if header data is
106 * different but body data is similar (binary, using the same datatypes).
107 *
108 * parameters:
109 * name <-- file name
110 * magic_string <-- magic string associated with file type
111 * mode <-- read or write
112 * method <-- file access method
113 * echo <-- echo on main output (< 0 if none, header if 0,
114 * n first and last elements if n > 0)
115 * hints <-- associated hints for MPI-IO, or MPI_INFO_NULL
116 * block_comm <-- handle to MPI communicator used for distributed file
117 * block access (may be a subset of comm if some ranks do
118 * not directly access distributed data blocks)
119 * comm <-- handle to main MPI communicator
120 *
121 * returns:
122 * pointer to kernel IO structure
123 *----------------------------------------------------------------------------*/
124
125#if defined(HAVE_MPI)
126
127cs_io_t *
128cs_io_initialize(const char *file_name,
129 const char *magic_string,
130 cs_io_mode_t mode,
131 cs_file_access_t method,
132 long echo,
133 MPI_Info hints,
134 MPI_Comm block_comm,
135 MPI_Comm comm);
136
137#else
138
139cs_io_t *
140cs_io_initialize(const char *file_name,
141 const char *magic_string,
142 cs_io_mode_t mode,
143 cs_file_access_t method,
144 long echo);
145
146#endif /* HAVE_MPI */
147
148/*----------------------------------------------------------------------------
149 * Initialize a kernel IO file structure in read mode, building an index.
150 *
151 * The magic string may be NULL, if we choose to ignore it.
152 *
153 * parameters:
154 * name <-- file name
155 * magic_string <-- magic string associated with file type
156 * method <-- file access method
157 * echo <-- echo on main output (< 0 if none, header if 0,
158 * n first and last elements if n > 0)
159 * hints <-- associated hints for MPI-IO, or MPI_INFO_NULL
160 * block_comm <-- handle to MPI communicator used for distributed file
161 * block access (may be a subset of comm if some ranks do
162 * not directly access distributed data blocks)
163 * comm <-- handle to main MPI communicator
164
165 * returns:
166 * pointer to kernel IO structure
167 *----------------------------------------------------------------------------*/
168
169#if defined(HAVE_MPI)
170
171cs_io_t *
172cs_io_initialize_with_index(const char *file_name,
173 const char *magic_string,
174 cs_file_access_t method,
175 long echo,
176 MPI_Info hints,
177 MPI_Comm block_comm,
178 MPI_Comm comm);
179#else
180
181cs_io_t *
182cs_io_initialize_with_index(const char *file_name,
183 const char *magic_string,
184 cs_file_access_t method,
185 long echo);
186
187#endif /* HAVE_MPI */
188
189/*----------------------------------------------------------------------------
190 * Free a preprocessor output file structure, closing the associated file.
191 *
192 * parameters:
193 * pp_io <-> kernel IO structure
194 *----------------------------------------------------------------------------*/
195
196void
197cs_io_finalize(cs_io_t **pp_io);
198
199/*----------------------------------------------------------------------------
200 * Return a pointer to a preprocessor IO structure's name.
201 *
202 * parameters:
203 * pp_io <-- kernel IO structure
204 *----------------------------------------------------------------------------*/
205
206const char *
207cs_io_get_name(const cs_io_t *pp_io);
208
209/*----------------------------------------------------------------------------
210 * Return the number of indexed entries in a kernel IO structure.
211 *
212 * parameters:
213 * inp <-- input kernel IO structure
214 *
215 * returns:
216 * size of index if present, 0 otherwise,
217 *----------------------------------------------------------------------------*/
218
219size_t
220cs_io_get_index_size(const cs_io_t *inp);
221
222/*----------------------------------------------------------------------------
223 * Return the name of an indexed section in a kernel IO structure.
224 *
225 * parameters:
226 * inp <-- input kernel IO structure
227 * id <-- id of section in index (0 to n-1 numbering)
228 *
229 * returns:
230 * pointer to section name if id in index range, NULL otherwise
231 *----------------------------------------------------------------------------*/
232
233const char *
235 size_t id);
236
237/*----------------------------------------------------------------------------
238 * Return header data for an indexed section in a kernel IO structure.
239 *
240 * parameters:
241 * inp <-- input kernel IO structure
242 * id <-- id of section in index (0 to n-1 numbering)
243 *
244 * returns:
245 * section header data (if id not in index range, fields set to zero)
246 *----------------------------------------------------------------------------*/
247
250 size_t id);
251
252/*----------------------------------------------------------------------------
253 * Return a kernel IO structure's echo (verbosity) level.
254 *
255 * parameters:
256 * pp_io <-- kernel IO structure
257 *----------------------------------------------------------------------------*/
258
259size_t
260cs_io_get_echo(const cs_io_t *pp_io);
261
262/*----------------------------------------------------------------------------
263 * Read a message header.
264 *
265 * parameters:
266 * pp_io <-- kernel IO structure
267 * header --> header structure
268 *
269 * returns:
270 * 0 if a header was read, 1 in case of error or end-of-file
271 *----------------------------------------------------------------------------*/
272
273int
275 cs_io_sec_header_t *header);
276
277/*----------------------------------------------------------------------------
278 * Set a kernel IO's state so as to be ready to read an indexed section.
279 *
280 * The header values and position in the file are set so as to be equivalent
281 * to those they would have if the corresponding header had just been read.
282 *
283 * parameters:
284 * inp <-> input kernel IO structure
285 * header --> associated header
286 * id <-- id of section in index (0 to n-1 numbering)
287 *
288 * returns:
289 * 0 in case of success, 1 in case of error
290 *----------------------------------------------------------------------------*/
291
292int
294 cs_io_sec_header_t *header,
295 size_t id);
296
297/*----------------------------------------------------------------------------
298 * Set a section's final data type to int.
299 *
300 * It the datatype is not compatible, throw an error.
301 *
302 * parameters:
303 * header <-- header structure
304 * cs_io --> kernel IO structure
305 *----------------------------------------------------------------------------*/
306
307void
309 const cs_io_t *cs_io);
310
311/*----------------------------------------------------------------------------
312 * Set a message's final data type to cs_lnum_t.
313 *
314 * It the datatype is not compatible, throw an error.
315 *
316 * parameters:
317 * header <-- header structure
318 * pp_io --> kernel IO structure
319 *----------------------------------------------------------------------------*/
320
321void
323 const cs_io_t *pp_io);
324
325/*----------------------------------------------------------------------------
326 * Set a message's final data type to cs_gnum_t.
327 *
328 * It the datatype is not compatible, throw an error.
329 *
330 * parameters:
331 * header <-> header structure
332 * pp_io <-- kernel IO structure
333 *----------------------------------------------------------------------------*/
334
335void
337 const cs_io_t *pp_io);
338
339/*----------------------------------------------------------------------------
340 * Check that a message's final data type corresponds to cs_real_t.
341 *
342 * parameters:
343 * header <-- header structure
344 * pp_io <-- kernel IO structure
345 *----------------------------------------------------------------------------*/
346
347void
349 const cs_io_t *pp_io);
350
351/*----------------------------------------------------------------------------
352 * Read a message body and replicate it to all processors.
353 *
354 * If the array intended to receive the data already exists, we pass an
355 * "elt" pointer to this array; this same pointer is then returned.
356 * Otherwise, if this pointer is passed as NULL, memory is allocated
357 * by this function, and the corresponding pointer is returned. It is
358 * the caller's responsibility to free this array.
359 *
360 * parameters:
361 * header <-- header structure
362 * elts <-> pointer to data array, or NULL
363 * pp_io --> kernel IO structure
364 *
365 * returns:
366 * elts if non NULL, or pointer to allocated array otherwise
367 *----------------------------------------------------------------------------*/
368
369void *
371 void *elts,
372 cs_io_t *pp_io);
373
374/*----------------------------------------------------------------------------
375 * Read a message body, assigning a different block to each processor.
376 *
377 * If location_id > 0 and header->n_location_vals > 1, then
378 * global_num_start and global_num_end will be based on location element
379 * numbers, so the total number of values read equals
380 * (global_num_end - global_num_start) * header->n_location_vals.
381 *
382 * If the array intended to receive the data already exists, we pass an
383 * "elt" pointer to this array; this same pointer is then returned.
384 * Otherwise, if this pointer is passed as NULL, memory is allocated
385 * by this function, and the corresponding pointer is returned. It is
386 * the caller's responsibility to free this array.
387 *
388 * parameters:
389 * header <-- header structure
390 * global_num_start <-- global number of first block item (1 to n numbering)
391 * global_num_end <-- global number of past-the end block item
392 * (1 to n numbering)
393 * elts <-> pointer to data array, or NULL
394 * pp_io --> kernel IO structure
395 *
396 * returns:
397 * elts if non NULL, or pointer to allocated array otherwise
398 *----------------------------------------------------------------------------*/
399
400void *
402 cs_gnum_t global_num_start,
403 cs_gnum_t global_num_end,
404 void *elts,
405 cs_io_t *pp_io);
406
407/*----------------------------------------------------------------------------
408 * Read a message body, assigning a different block to each processor,
409 * when the body corresponds to an index.
410 *
411 * In serial mode, this function behaves just like cs_io_read_block(),
412 * except that it allows only unsigned integer values (cs_gnum_t).
413 *
414 * In parallel mode, global_num_end should be set to the past-the-end value
415 * of the base data block, the same as for regular data (and not increased
416 * by 1 for the last rank, as this will be handled internally).
417 * On each rank, the buffer size should be:
418 * global_num_end - global_num_start + 1, as the past-the end index
419 * for the local block is added automatically.
420 *
421 * If the array intended to receive the data already exists, we pass an
422 * "elt" pointer to this array; this same pointer is then returned.
423 * Otherwise, if this pointer is passed as NULL, memory is allocated
424 * by this function, and the corresponding pointer is returned. It is
425 * the caller's responsibility to free this array.
426 *
427 * parameters:
428 * header <-- header structure
429 * global_num_start <-- global number of first block item (1 to n numbering)
430 * global_num_end <-- global number of past-the end block item
431 * (1 to n numbering)
432 * elts <-> pointer to data array, or NULL
433 * pp_io --> kernel IO structure
434 *
435 * returns:
436 * elts if non NULL, or pointer to allocated array otherwise
437 *----------------------------------------------------------------------------*/
438
439void *
441 cs_gnum_t global_num_start,
442 cs_gnum_t global_num_end,
443 cs_gnum_t *elts,
444 cs_io_t *pp_io);
445
446/*----------------------------------------------------------------------------
447 * Write a global section.
448 *
449 * Under MPI, data is only written by the associated communicator's root
450 * rank. The section data on other ranks is ignored, though the file offset
451 * is updated (i.e. the call to this function is collective).
452 *
453 * parameters:
454 * section_name <-- section name
455 * n_vals <-- total number of values
456 * location_id <-- id of associated location, or 0
457 * index_id <-- id of associated index, or 0
458 * n_location_vals <-- number of values per location
459 * elt_type <-- element type
460 * elts <-- pointer to element data
461 * outp <-> output kernel IO structure
462 *----------------------------------------------------------------------------*/
463
464void
465cs_io_write_global(const char *sec_name,
466 cs_gnum_t n_vals,
467 size_t location_id,
468 size_t index_id,
469 size_t n_location_vals,
470 cs_datatype_t elt_type,
471 const void *elts,
472 cs_io_t *outp);
473
474/*----------------------------------------------------------------------------
475 * Write a section to file, each associated process providing a contiguous
476 * of the section's body.
477 *
478 * Each process should provide a (possibly empty) block of the body,
479 * and we should have:
480 * global_num_start at rank 0 = 1
481 * global_num_start at rank i+1 = global_num_end at rank i.
482 * Otherwise, behavior (especially positioning for future reads) is undefined.
483 *
484 * If location_id > 0 and n_location_vals > 1, then global_num_start
485 * and global_num_end will be based on location element numbers, so the
486 * total number of values read equals
487 * (global_num_end - global_num_start) * header->n_location_vals.
488 *
489 * This function does not modify the values in its input buffer (notably,
490 * a copy is used to convert from little-endian to big-endian or vice-versa
491 * if necessary).
492 *
493 * parameters:
494 * section_name <-- section name
495 * n_g_elts <-- number of global elements (locations)
496 * global_num_start <-- global number of first block item (1 to n numbering)
497 * global_num_end <-- global number of past-the end block item
498 * location_id <-- id of associated location, or 0
499 * index_id <-- id of associated index, or 0
500 * n_location_vals <-- number of values per location
501 * elt_type <-- element type
502 * (1 to n numbering)
503 * elts <-- pointer to element data
504 * outp <-> output kernel IO structure
505 *----------------------------------------------------------------------------*/
506
507void
508cs_io_write_block(const char *sec_name,
509 cs_gnum_t n_g_elts,
510 cs_gnum_t global_num_start,
511 cs_gnum_t global_num_end,
512 size_t location_id,
513 size_t index_id,
514 size_t n_location_vals,
515 cs_datatype_t elt_type,
516 const void *elts,
517 cs_io_t *outp);
518
519/*----------------------------------------------------------------------------
520 * Write a section to file, each associated process providing a contiguous
521 * of the section's body.
522 *
523 * Each process should provide a (possibly empty) block of the body,
524 * and we should have:
525 * global_num_start at rank 0 = 1
526 * global_num_start at rank i+1 = global_num_end at rank i.
527 * Otherwise, behavior (especially positioning for future reads) is undefined.
528 *
529 * If location_id > 0 and n_location_vals > 1, then global_num_start
530 * and global_num_end will be based on location element numbers, so the
531 * total number of values read equals
532 * (global_num_end - global_num_start) * header->n_location_vals.
533 *
534 * This function is intended to be used mainly on data that is already of
535 * copy of original data (such as data that has been redistributed across
536 * processors just for the sake of output), or that is to be deleted after
537 * writing, so it may modify the values in its input buffer (notably to
538 * convert from little-endian to big-endian or vice-versa if necessary).
539 *
540 * parameters:
541 * section_name <-- section name
542 * n_g_elts <-- number of global elements (locations)
543 * global_num_start <-- global number of first block item (1 to n numbering)
544 * global_num_end <-- global number of past-the end block item
545 * location_id <-- id of associated location, or 0
546 * index_id <-- id of associated index, or 0
547 * n_location_vals <-- number of values per location
548 * elt_type <-- element type
549 * (1 to n numbering)
550 * elts <-- pointer to element data
551 * outp <-> output kernel IO structure
552 *----------------------------------------------------------------------------*/
553
554void
555cs_io_write_block_buffer(const char *sec_name,
556 cs_gnum_t n_g_elts,
557 cs_gnum_t global_num_start,
558 cs_gnum_t global_num_end,
559 size_t location_id,
560 size_t index_id,
561 size_t n_location_vals,
562 cs_datatype_t elt_type,
563 void *elts,
564 cs_io_t *outp);
565
566/*----------------------------------------------------------------------------
567 * Skip a message.
568 *
569 * parameters:
570 * header <-- header structure
571 * pp_io --> kernel IO structure
572 *----------------------------------------------------------------------------*/
573
574void
575cs_io_skip(const cs_io_sec_header_t *header,
576 cs_io_t *pp_io);
577
578/*----------------------------------------------------------------------------
579 * Return the position of the file pointer for an open kernel IO file.
580 *
581 * parameters:
582 * inp <-- input kernel IO structure
583 *
584 * returns:
585 * offset in file
586 *----------------------------------------------------------------------------*/
587
590
591/*----------------------------------------------------------------------------
592 * Set the position of the file pointer for an open kernel IO file.
593 *
594 * parameters:
595 * inp <-- input kernel IO structure
596 * offset <-- offset in file
597 *----------------------------------------------------------------------------*/
598
599void
601 cs_file_off_t offset);
602
603/*----------------------------------------------------------------------------
604 * Initialize performance logging for cs_io_t structures.
605 *----------------------------------------------------------------------------*/
606
607void
609
610/*----------------------------------------------------------------------------
611 * Finalize performance logging for cs_io_t structures.
612 *----------------------------------------------------------------------------*/
613
614void
616
617/*----------------------------------------------------------------------------
618 * Dump a kernel IO file handle's metadata.
619 *
620 * parameters:
621 * cs_io <-- kernel IO structure
622 *----------------------------------------------------------------------------*/
623
624void
625cs_io_dump(const cs_io_t *cs_io);
626
627/*----------------------------------------------------------------------------*/
628
630
631#endif /* __CS_IO_H__ */
cs_datatype_t
Definition cs_defs.h:272
#define BEGIN_C_DECLS
Definition cs_defs.h:509
#define END_C_DECLS
Definition cs_defs.h:510
long long cs_file_off_t
Definition cs_file.h:107
cs_file_access_t
Definition cs_file.h:84
cs_io_t * cs_io_initialize_with_index(const char *file_name, const char *magic_string, cs_file_access_t method, long echo, MPI_Info hints, MPI_Comm block_comm, MPI_Comm comm)
Definition cs_io.c:1882
void cs_io_log_finalize(void)
Definition cs_io.c:3154
const char * cs_io_get_name(const cs_io_t *pp_io)
Definition cs_io.c:1991
cs_io_mode_t
Definition cs_io.h:59
@ CS_IO_MODE_READ
Definition cs_io.h:61
@ CS_IO_MODE_WRITE
Definition cs_io.h:62
int cs_glob_io_hints
size_t cs_io_get_echo(const cs_io_t *pp_io)
Definition cs_io.c:2101
void cs_io_set_int(cs_io_sec_header_t *header, const cs_io_t *cs_io)
Definition cs_io.c:2398
const char * cs_io_get_indexed_sec_name(const cs_io_t *inp, size_t id)
Definition cs_io.c:2031
size_t cs_io_get_index_size(const cs_io_t *inp)
Definition cs_io.c:2009
void cs_io_write_global(const char *sec_name, cs_gnum_t n_vals, size_t location_id, size_t index_id, size_t n_location_vals, cs_datatype_t elt_type, const void *elts, cs_io_t *outp)
Definition cs_io.c:2784
void cs_io_log_initialize(void)
Definition cs_io.c:3137
void cs_io_finalize(cs_io_t **pp_io)
Definition cs_io.c:1953
int cs_io_read_header(cs_io_t *inp, cs_io_sec_header_t *header)
Definition cs_io.c:2123
void cs_io_write_block(const char *sec_name, cs_gnum_t n_g_elts, cs_gnum_t global_num_start, cs_gnum_t global_num_end, size_t location_id, size_t index_id, size_t n_location_vals, cs_datatype_t elt_type, const void *elts, cs_io_t *outp)
Definition cs_io.c:2875
void cs_io_assert_cs_real(const cs_io_sec_header_t *header, const cs_io_t *pp_io)
Definition cs_io.c:2506
void * cs_io_read_block(const cs_io_sec_header_t *header, cs_gnum_t global_num_start, cs_gnum_t global_num_end, void *elts, cs_io_t *pp_io)
Definition cs_io.c:2575
void cs_io_set_cs_lnum(cs_io_sec_header_t *header, const cs_io_t *pp_io)
Definition cs_io.c:2435
cs_io_sec_header_t cs_io_get_indexed_sec_header(const cs_io_t *inp, size_t id)
Definition cs_io.c:2058
void cs_io_write_block_buffer(const char *sec_name, cs_gnum_t n_g_elts, cs_gnum_t global_num_start, cs_gnum_t global_num_end, size_t location_id, size_t index_id, size_t n_location_vals, cs_datatype_t elt_type, void *elts, cs_io_t *outp)
Definition cs_io.c:2976
void cs_io_set_cs_gnum(cs_io_sec_header_t *header, const cs_io_t *pp_io)
Definition cs_io.c:2472
cs_io_t * cs_io_initialize(const char *file_name, const char *magic_string, cs_io_mode_t mode, cs_file_access_t method, long echo, MPI_Info hints, MPI_Comm block_comm, MPI_Comm comm)
Definition cs_io.c:1819
int cs_io_set_indexed_position(cs_io_t *inp, cs_io_sec_header_t *header, size_t id)
Definition cs_io.c:2334
cs_file_off_t cs_io_get_offset(cs_io_t *inp)
Definition cs_io.c:3104
void cs_io_set_offset(cs_io_t *inp, cs_file_off_t offset)
Definition cs_io.c:3121
void * cs_io_read_index_block(cs_io_sec_header_t *header, cs_gnum_t global_num_start, cs_gnum_t global_num_end, cs_gnum_t *elts, cs_io_t *pp_io)
Definition cs_io.c:2624
void * cs_io_read_global(const cs_io_sec_header_t *header, void *elts, cs_io_t *pp_io)
Definition cs_io.c:2541
void cs_io_dump(const cs_io_t *cs_io)
Definition cs_io.c:3260
struct _cs_io_t cs_io_t
Definition cs_io.h:68
void cs_io_skip(const cs_io_sec_header_t *header, cs_io_t *pp_io)
Definition cs_io.c:3050
Definition cs_io.h:73
const char * sec_name
Definition cs_io.h:75
size_t location_id
Definition cs_io.h:77
size_t n_location_vals
Definition cs_io.h:79
cs_datatype_t elt_type
Definition cs_io.h:80
size_t index_id
Definition cs_io.h:78
cs_file_off_t n_vals
Definition cs_io.h:76
cs_datatype_t type_read
Definition cs_io.h:81