1 #ifndef __CS_TIME_CONTROL_H__
2 #define __CS_TIME_CONTROL_H__
3 
4 /*============================================================================
5  * Time dependency control for variables or properties.
6  *============================================================================*/
7 
8 /*
9   This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11   Copyright (C) 1998-2021 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 /*----------------------------------------------------------------------------
31  * Standard C library headers
32  *----------------------------------------------------------------------------*/
33 
34 #include <stdarg.h>
35 
36 /*----------------------------------------------------------------------------
37  *  Local headers
38  *----------------------------------------------------------------------------*/
39 
40 #include "cs_defs.h"
41 
42 #include "cs_time_step.h"
43 
44 /*----------------------------------------------------------------------------*/
45 
46 BEGIN_C_DECLS
47 
48 /*=============================================================================
49  * Macro definitions
50  *============================================================================*/
51 
52 /*============================================================================
53  * Type definitions
54  *============================================================================*/
55 
56 /*----------------------------------------------------------------------------*/
57 /*!
58  * \brief  Function pointer to a time control function.
59  *
60  * Each function of this sort may be used to determine whether a given
61  * set of operations (such as variable or property updates) should
62  * be done at the current time step.
63  *
64  * \remark: if the input pointer is non-NULL, it must point to valid data
65  *          when the control function is called, so that value or structure
66  *          should not be temporary (i.e. local);
67  *
68  * \param[in]  ts     current time step structure
69  * \param[in]  input  pointer to optional (untyped) value or structure, or NULL.
70  *
71  * \return  true if active at given time step, false oltherwise
72  */
73 /*----------------------------------------------------------------------------*/
74 
75 typedef bool
76 (cs_time_control_func_t) (const cs_time_step_t  *ts,
77                           void                  *input);
78 
79 /* Time control types */
80 /*--------------------*/
81 
82 /* Datatype enumeration */
83 
84 typedef enum {
85 
86   CS_TIME_CONTROL_TIME_STEP,     /*!< control based on time step */
87   CS_TIME_CONTROL_TIME,          /*!< control based on simulated time */
88   CS_TIME_CONTROL_FUNCTION,      /*!< control based on function */
89 
90 } cs_time_control_type_t;
91 
92 /*----------------------------------------------------------------------------
93  * Time control structure
94  *----------------------------------------------------------------------------*/
95 
96 typedef struct {
97 
98   /* Type and control parameters */
99 
100   cs_time_control_type_t  type;   /* control type */
101 
102   bool       at_start;            /* always active at start ? */
103   bool       at_end;              /* always active at end ? */
104 
105   union {
106     int      start_nt;            /* update start time step */
107     double   start_t;             /* update start physical time */
108   };
109 
110   union {
111     int      end_nt;              /* update end time step */
112     double   end_t;               /* update end physical time */
113   };
114 
115   union {
116     int      interval_nt;         /* interval, in time steps */
117     double   interval_t;          /* interval, in physical time units */
118   };
119 
120   cs_time_control_func_t  *control_func;   /* function for advanced control */
121   void                    *control_input;  /* input associated function */
122 
123   /* Current state */
124 
125   bool    current_state;          /* query return value of current time step */
126   int     current_time_step;      /* last time step queried */
127 
128   int     last_nt;                /* last active time step */
129   double  last_t;                 /* last active physical time */
130 
131 }  cs_time_control_t;
132 
133 /*============================================================================
134  * Global variables
135  *============================================================================*/
136 
137 /*=============================================================================
138  * Public function prototypes
139  *============================================================================*/
140 
141 /*----------------------------------------------------------------------------
142  *!
143  * \brief Indicate if a time control is active or not at the given time.
144  *
145  * If the time control or time step argument is NULL, true is returned.
146  *
147  * \param[in]  tc  time control structure
148  * \param[in]  ts  time step structure
149  *
150  * \return  true if active, false if inactive
151  */
152 /*----------------------------------------------------------------------------*/
153 
154 bool
155 cs_time_control_is_active(cs_time_control_t     *tc,
156                           const cs_time_step_t  *ts);
157 
158 /*----------------------------------------------------------------------------
159  *!
160  * \brief Simple time control initialization based on time step options.
161  *
162  * \param[in]  tc        pointer to time control structure.
163  * \param[in]  nt_start  start time step (or < 0 for unlimited)
164  * \param[in]  nt_end    end time step (or < 0 for unlimited)
165  * \param[in]  at_start  always active at start ?
166  * \param[in]  at_start  always active at end ?
167  */
168 /*----------------------------------------------------------------------------*/
169 
170 void
171 cs_time_control_init_by_time_step(cs_time_control_t  *tc,
172                                   int                 nt_start,
173                                   int                 nt_end,
174                                   int                 nt_interval,
175                                   bool                at_start,
176                                   bool                at_end);
177 
178 /*----------------------------------------------------------------------------
179  *!
180  * \brief Simple time control initialization based on physical time options.
181  *
182  * \param[in]  tc        pointer to time control structure.
183  * \param[in]  t_start   start time (or < 0 for unlimited)
184  * \param[in]  t_end     end time (or < 0 for unlimited)
185  * \param[in]  at_start  always active at start ?
186  * \param[in]  at_start  always active at end ?
187  */
188 /*----------------------------------------------------------------------------*/
189 
190 void
191 cs_time_control_init_by_time(cs_time_control_t  *tc,
192                              double              t_start,
193                              double              t_end,
194                              double              t_interval,
195                              bool                at_start,
196                              bool                at_end);
197 
198 /*----------------------------------------------------------------------------
199  *!
200  * \brief Simple time control initialization based on external function.
201  *
202  * \remark: if the input pointer is non-NULL, it must point to valid data
203  *          when the control function is called, so that value or structure
204  *          should not be temporary (i.e. local);
205  *
206  * \param[in]  tc             pointer to time control structure.
207  * \param[in]  control_func   pointer to time control funcction.
208  * \param[in]  control_input  pointer to optional (untyped) value or structure,
209  *                            or NULL.
210  * \param[in]  at_start       always active at start ?
211  * \param[in]  at_start       always active at end ?
212  */
213 /*----------------------------------------------------------------------------*/
214 
215 void
216 cs_time_control_init_by_func(cs_time_control_t       *tc,
217                              cs_time_control_func_t  *control_func,
218                              void                    *control_input,
219                              bool                     at_start,
220                              bool                     at_end);
221 
222 /*----------------------------------------------------------------------------
223  *!
224  * \brief Get text description of time control configuration.
225  *
226  * If the time control or time step argument is NULL, true is returned.
227  *
228  * \param[in]   tc         time control structure
229  * \param[out]  desc       description string
230  * \param[in]   desc_size  description string maximum size
231  *
232  * \return  true if active, false if inactive
233  */
234 /*----------------------------------------------------------------------------*/
235 
236 void
237 cs_time_control_get_description(const cs_time_control_t  *tc,
238                                 char                     *desc,
239                                 size_t                    desc_size);
240 
241 /*----------------------------------------------------------------------------*/
242 
243 END_C_DECLS
244 
245 #endif /* __CS_TIME_CONTROL_H__ */
246