Coverage for fiqus/data/DataModelCommon.py: 100%
141 statements
« prev ^ index » next coverage.py v7.4.4, created at 2025-10-30 01:48 +0000
1from pydantic import BaseModel, Field
3from typing import List, Union, Optional, Literal
6############################
7# Circuit
8class Circuit_Class(BaseModel):
9 """
10 Level 1: Class for the circuit parameters
11 """
12 field_circuit: Optional[bool] = Field(
13 default = False,
14 description = "Allows to use Field-Circuit Coupling equations in the model.")
15 R_circuit: Optional[float] = None # R_circuit
16 L_circuit: Optional[float] = None # Lcir (SIGMA)
17 R_parallel: Optional[float] = None
20############################
21# Power Supply (aka Power Converter)
22class PowerSupplyClass(BaseModel):
23 """
24 Level 1: Class for the power supply (aka power converter)
25 """
26 I_initial: Optional[float] = Field(
27 default=None,
28 description="Initial current in the magnet. Propagated differently in various tools and obsolete # I00 (LEDET), I_0 (SIGMA), I0 (BBQ)")
29 t_off: Optional[float] = Field(
30 default=None,
31 description="Time of switching off the switch next to current controlled source. t_PC (LEDET)")
32 t_control_LUT: List[float] = Field(
33 default=[],
34 description="List of time values [s] for linear piece wise time function of current controlled source. t_PC_LUT (LEDET)")
35 I_control_LUT: List[float] = Field(
36 default=[],
37 description="List of current values [A] for linear piece wise time function of current controlled source. I_PC_LUT (LEDET)")
38 R_crowbar: Optional[float] = Field(
39 default=0,
40 description="Crowbar resistance in forward direction [Ohm]. Rcrow (SIGMA), RCrowbar (ProteCCT)")
41 L_crowbar: Optional[float] = Field(
42 default=0,
43 description="Crowbar inductance in forward direction [H].")
44 Ud_crowbar: Optional[float] = Field(
45 default=0,
46 description="Crowbar diode voltage in forward direction [V].")
47 R_c_r: Optional[float] = Field(
48 default=0,
49 description="Crowbar resistance in reverse direction [Ohm].")
50 L_c_r: Optional[float] = Field(
51 default=0,
52 description="Crowbar inductance in reverse direction [H].")
53 Ud_c_r: Optional[float] = Field(
54 default=0,
55 description="Crowbar diode voltage in reverse direction [V].")
56 R_1: Optional[float] = Field(
57 default=0,
58 description="Resistance R1 [Ohm].")
59 L_1: Optional[float] = Field(
60 default=0,
61 description="Inductance L1 [H].")
62 R_2: Optional[float] = Field(
63 default=0,
64 description="Resistance R2 [Ohm].")
65 L_2: Optional[float] = Field(
66 default=0,
67 description="Inductance L2 [H].")
68 C: Optional[float] = Field(
69 default=0,
70 description="Capacitance C [F].")
71 R_3: Optional[float] = Field(
72 default=0,
73 description="Resistance R3 [Ohm].")
74 L_3: Optional[float] = Field(
75 default=0,
76 description="Inductance L3 [H].")
78############################
79# Quench Protection
80class EnergyExtraction(BaseModel):
81 """
82 Level 2: Class for the energy extraction parameters
83 """
84 t_trigger: Optional[float] = Field(
85 default=99999.0,
86 description="Trigger time on the positive lead [s]. tEE (LEDET), tSwitchDelay (ProteCCT)")
87 R_EE: Optional[float] = Field(
88 default=0,
89 description="Energy extraction resistance on the positive lead [Ohm]. R_EE_triggered (ProteCCT)")
90 power_R_EE: Optional[float] = Field(
91 default=0.0,
92 description="Varistor power component, R(I) = R_EE*abs(I)^power_R_EE on the positive lead [-]. RDumpPower (ProteCCT)")
93 L: Optional[float] = Field(
94 default=0,
95 description="Inductance in series with resistor on the positive lead [H].")
96 C: Optional[float] = Field(
97 default=0,
98 description="Snubber capacitance in parallel to the EE switch on the positive lead [F].")
99 L_c: Optional[float] = Field(
100 default=0,
101 description="Inductance in the snubber capacitance branch in parallel to the EE switch on the positive lead [H].")
102 R_c: Optional[float] = Field(
103 default=0,
104 description="Resistance in the snubber capacitance branch in parallel to the EE switch on the positive lead [Ohm].")
105 Ud_snubber: Optional[float] = Field(
106 default=0,
107 description="Forward voltage of diode in the snubber capacitance branch in parallel to the EE switch on the positive lead [V].")
108 L_s: Optional[float] = Field(
109 default=0,
110 description="Inductance in the EE switch branch on the positive lead [H].")
111 R_s: Optional[float] = Field(
112 default=0,
113 description="Resistance in the EE switch branch on the positive lead [Ohm].")
114 Ud_switch: Optional[float] = Field(
115 default=0,
116 description="Forward voltage of diode in the EE switch branch on the positive lead [V].")
118 t_trigger_n: Optional[float] = Field(
119 default=99999.0,
120 description="Trigger time on the negative lead [s]. tEE (LEDET), tSwitchDelay (ProteCCT)")
121 R_EE_n: Optional[float] = Field(
122 default=0,
123 description="Energy extraction resistance on the negative lead [Ohm]. R_EE_triggered (ProteCCT)")
124 power_R_EE_n: Optional[float] = Field(
125 default=0.0,
126 description="Varistor power component, R(I) = R_EE*abs(I)^power_R_EE on the negative lead [-]. RDumpPower (ProteCCT)")
127 L_n: Optional[float] = Field(
128 default=0,
129 description="Inductance in series with resistor on the negative lead [H].")
130 C_n: Optional[float] = Field(
131 default=0,
132 description="Snubber capacitance in parallel to the EE switch on the negative lead [F].")
133 L_c_n: Optional[float] = Field(
134 default=0,
135 description="Inductance in the snubber capacitance branch in parallel to the EE switch on the negative lead [H].")
136 R_c_n: Optional[float] = Field(
137 default=0,
138 description="Resistance in the snubber capacitance branch in parallel to the EE switch on the negative lead [Ohm].")
139 Ud_snubber_n: Optional[float] = Field(
140 default=0,
141 description="Forward voltage of diode in the snubber capacitance branch in parallel to the EE switch on the negative lead [V].")
142 L_s_n: Optional[float] = Field(
143 default=0,
144 description="Inductance in the EE switch branch on the negative lead [H].")
145 R_s_n: Optional[float] = Field(
146 default=0,
147 description="Resistance in the EE switch branch on the negative lead [Ohm].")
148 Ud_switch_n: Optional[float] = Field(
149 default=0,
150 description="Forward voltage of diode in the EE switch branch on the negative lead [V].")
153class QuenchHeater(BaseModel):
154 """
155 Level 2: Class for the quench heater parameters
156 """
157 N_strips: Optional[int] = Field(
158 default=None,
159 description="Number of quench heater traces (typically 2 traces make one pad)")
160 t_trigger: List[float] = Field(
161 default=[],
162 description="Trigger times list of of quench heaters [s]")
163 U0: List[float] = Field(
164 default=[],
165 description="Initial charging voltages list of capacitor for the trance (not full pad!) [V]")
166 C: List[float] = Field(
167 default=[],
168 description="Capacitances list of quench heater power supply for the trance (not full pad!) [H]")
169 R_warm: List[float] = Field(
170 default=[],
171 description="Internal resistances list of quench heater power supply and/or additional resistance added to limit the heater current for the trance (not full pad!) [Ohm]")
172 w: List[float] = Field(
173 default=[],
174 description="Widths list of quench heater trance stainless steel part [m]")
175 h: List[float] = Field(
176 default=[],
177 description="Thickness list of quench heater trance stainless steel part [m]")
178 h_ins: Union[List[float], List[List[float]]] = Field(
179 default=[],
180 description="Thickness list of quench heater insulation between the stainless steel part and conductor insulation [m]"
181 "This could be a list of list to specify multiple material thicknesses")
182 type_ins: Union[List[str], List[List[str]]] = Field(
183 default=[],
184 description="Material names list of quench heater insulation between the stainless steel part and conductor insulation [-]"
185 "This could be a list of list to specify multiple material names")
186 h_ground_ins: Union[List[float], List[List[float]]] = Field(
187 default=[],
188 description="Material names list of quench heater insulation between the stainless steel part and helium bath [-]"
189 "This could be a list of list to specify multiple material thicknesses")
190 type_ground_ins: Union[List[str], List[List[str]]] = Field(
191 default=[],
192 description="Material names list of quench heater insulation between the stainless steel part and helium bath [-]"
193 "This could be a list of list to specify multiple material names")
194 l: List[float] = Field(
195 default=[],
196 description="Lengths list of quench heaters [m]. Typically equal to magnet length.")
197 l_copper: List[float] = Field(
198 default=[],
199 description="Lengths list of copper laminations of quench heaters [m].")
200 l_stainless_steel: List[float] = Field(
201 default=[],
202 description="Lengths list of stainless steel only sections of quench heaters [m].")
203 f_cover: List[float] = Field(
204 default=[],
205 description="List of fraction of stainless steel cover. This is l_stainless_steel/(l_stainless_steel+l_copper). Marked as obsolete, but still specified in some models [-].")
206 ids: List[int] = Field(
207 default=[],
208 description="List of heater numbers (1 based) equal to the length of turns that are covered by (i.e. thermally connected to) quench heaters.")
209 turns: List[int] = Field(
210 default=[],
211 description="List of turn numbers (1 based) that are covered by (i.e. thermally connected to) quench heaters.")
212 turns_sides: List[str] = Field(
213 default=[],
214 description="List of letters specifying side of turn where quench heater is placed. Only used in FiQuS Multipole module."
215 "Possible sides are: 'o' - outer, 'i' - inner, 'l' - lower angle, 'h' - higher angle.")
216 quench_propagation: Optional[Literal['2Dx1D','full']] = Field(
217 default = "full",
218 description = 'Enables to have a variable length for the quench heater, different from the full magnet length.')
219 quench_prop_model: Optional[Literal['Wilson','Ts']] = Field(
220 default = "Ts",
221 description = 'Selects the model used for the material properties of the quench propagation. "Wilson" uses a scaled cv and Ts uses the cv at Ts.')
222 NZPV_multiplier: Optional[float] = Field(
223 default = 1.0,
224 description = 'Factor that multiplies the Normal Zone Propagation Velocity')
225 L_QH_offset: Optional[List[float]] = Field(
226 default = [],
227 description= 'Offset of the quench heater strip from the referrence point located at the middle of the magnet length. Positive values move the quench heater towards higher z values (move quench heater strip towards the front ofthe magnet).')
229class CLIQ_Class(BaseModel):
230 """
231 Level 2: Class for the CLIQ parameters
232 """
233 t_trigger: Optional[float] = Field(
234 default=99999.0,
235 description="Trigger time of CLIQ unit [s].")
236 current_direction: List[int] = Field(
237 default=[],
238 description="Polarity of current in groups specified as a list with length equal to the number of groups [-].")
239 sym_factor: Optional[float] = Field(
240 default=None,
241 description="Obsolete.")
242 N_units: Optional[int] = Field(
243 default=None,
244 description="Obsolete.")
245 U0: Optional[float] = Field(
246 default=0,
247 description="Initial charging voltage of CLIQ unit [V].")
248 C: Optional[float] = Field(
249 default=0,
250 description="Capacitance of CLIQ unit [F].")
251 R: Optional[float] = Field(
252 default=0,
253 description="Resistance of CLIQ unit [Ohm].")
254 L: Optional[float] = Field(
255 default=0,
256 description="Inductance of CLIQ unit [H].")
257 I0: Optional[float] = Field(
258 default=None,
259 description="Obsolete.")
262class ESC_Class(BaseModel):
263 """
264 Level 2: Class for the ESC parameters
265 """
266 t_trigger: List[float] = Field(
267 default=[],
268 description="Trigger time of ESC units [s] given as a list with length corresponding to the number of ESC units.")
269 U0: List[float] = Field(
270 default=[],
271 description="Initial charging voltage of ESC units [V] given as a list with length corresponding to the number of ESC units."
272 "The unit is grounded in the middle, so the voltage to ground is half of this value")
273 C: List[float] = Field(
274 default=[],
275 description="Capacitance of ESC units [F] given as a list with length corresponding to the number of ESC units."
276 "The unit is grounded in the middle, with two capacitors in series with value of 2C")
277 L: List[float] = Field(
278 default=[],
279 description="Parasitic inductance of ESC units [H] given as a list with length corresponding to the number of ESC units."
280 "The unit is grounded in the middle, with two capacitors in series with value of 2C")
281 R_unit: List[float] = Field(
282 default=[],
283 description="Internal resistance of ESC units [Ohm] given as a list with length corresponding to the number of ESC units.")
284 R_leads: List[float] = Field(
285 default=[],
286 description="Resistance of leads from ESC coil to ESC diode connections [Ohm] given as a list with length corresponding to the number of ESC units.")
287 Ud_Diode: List[float] = Field(
288 default=[],
289 description="Forward diodes voltage across ESC coils [V] given as a list with length corresponding to the number of ESC units.")
290 L_Diode: List[float] = Field(
291 default=[],
292 description="Inductance in series with diodes across ESC coils [V] given as a list with length corresponding to the number of ESC units.")
295class FQPCs_Class(BaseModel):
296 """
297 Level 2: Class for the FQPLs parameters for protection
298 """
299 enabled: Optional[List[bool]] = Field(
300 default=None,
301 description="List of booleans specifying which FQPC is enabled.")
302 names: Optional[List[str]] = Field(
303 default=None,
304 description="List of names to use in gmsh and getdp. Any unique ASCII strings would work")
305 fndpls: Optional[List[int]] = Field(
306 default=None,
307 description="List of FQPC number of divisions per length at geometry level [-]")
308 fwws: Optional[List[float]] = Field(
309 default=None,
310 description="List of FQPC wire widths (assuming rectangular). For theta = 0 this is x dimension. Works at geometry level [-]")
311 fwhs: Optional[List[float]] = Field(
312 default=None,
313 description="List of FQPC wire heights (assuming rectangular). For theta = 0 this is y dimension. Works at geometry level [-]")
314 r_ins: Optional[List[float]] = Field(
315 default=None,
316 description="List of FQPC inner diameter of (e.g. for CCT magnet). For theta = 0 this is x dimension. Works at geometry level [-]")
317 r_bs: Optional[List[float]] = Field(
318 default=None,
319 description="List of FQPC radiuses for bending the fqpl by 180 degrees at the end of the magnet to go backward. Works at geometry level [-]")
320 n_sbs: Optional[List[int]] = Field(
321 default=None,
322 description="List of FQPC number of 'bending segments' for the 180 degrees turn. Works at geometry level [-]")
323 thetas: Optional[List[float]] = Field(
324 default=None,
325 description="List of FQPC rotation in deg from x+ axis towards y+ axis about z axis. Works at geometry level [-]")
326 z_starts: Optional[List[str]] = Field(
327 default=None,
328 description="List of z coordinates for the air boundary to start at. These are string with either: z_min or z_max key from the Air region. Works at geometry level [-]")
329 z_ends: Optional[List[float]] = Field(
330 default=None,
331 description="List of z coordinates for the air boundary to end at. These are string with either: z_min or z_max key from the Air region. Works at geometry level [-]")
332 currents: Optional[List[float]] = Field(
333 default=None,
334 description="List of FQPC currents for a magnetostatic solution. Works at solve level [-]")
335 sigmas: Optional[List[float]] = Field(
336 default=None,
337 description="List of FQPC electrical conductivity for a magnetostatic solution. Works at solve level [-]")
338 mu_rs: Optional[List[float]] = Field(
339 default=None,
340 description="List of FQPC magnetic permeability for a magnetostatic solution. Works at solve level [-]")
341 th_conns_def: Optional[List[List]] = Field(
342 default=None,
343 description="List of lists specifying thermal connections for LEDET to connect the FQPCs to the other turns of the magnet")
345class SourceSine(BaseModel):
346 """
347 Level 3: Class for Sine source parameters for E-CLIQ
348 """
349 frequency: Optional[float] = Field(default=None, description="Frequency of the sine source (Hz).")
350 current_amplitude: Optional[float] = Field(default=None, description="Amplitude of the sine current (A).")
351 number_of_periods: Optional[float] = Field(default=None, description="Amplitude of the sine current (A).")
353class SourcePiecewise(BaseModel):
354 """
355 Level 3 Class for piecewise (linear) source parameters for E-CLIQ
356 """
357 csv_file: Optional[str] = Field(default=None, description="File name for the from_file source type defining the time evolution of current. Multipliers are used for each of them. The file should contain two columns: 'time' (s) and 'current' (A), with these headers. If this field is set, times and currents are ignored.")
358 times: Optional[List[float]] = Field(default=None, description="Time instants (s) defining the piecewise linear sources. Used only if source_csv_file is not set. Can be scaled by time_multiplier.")
359 currents: Optional[List[float]] = Field(default=None, description="E-CLIQ coil currents relative to current_multiplier at the time instants 'times'. Used only if source_csv_file is not set.")
360 time_multiplier: Optional[float] = Field(default=None, description="Multiplier for the time values in times (scales the time values). Also used for the time values in the source_csv_file.")
361 current_multiplier: Optional[float] = Field(default=None, description="Multiplier for the E-CLIQ coil currents in currents. Also used for the values in the source_csv_file.")
363class E_CLIQ_Class(BaseModel):
364 """
365 Level 2: Class for the E-CLIQ parameters for protection
366 """
367 t_trigger: Optional[List[float]] = Field(
368 default=[],
369 description="Trigger time of E-CLIQ current sources [s] given as a list with length corresponding to the number of E-CLIQ units.")
370 R_leads: Optional[List[float]] = Field(
371 default=None,
372 description="List of E-CLIQ unit lead resistances [Ohm]. List length corresponding to the number of E-CLIQ units.")
373 L_leads: Optional[List[float]] = Field(
374 default=None,
375 description="List of E-CLIQ unit lead inductances [H]. List length corresponding to the number of E-CLIQ units.")
376 source_type: Literal['sine', 'piecewise', None] = Field(
377 default=None,
378 description="Time evolution of applied current. Supported options are: sine, piecewise.")
379 sine: SourceSine = Field(
380 default=SourceSine(),
381 description="Definition of sine current source parameters.")
382 piecewise: SourcePiecewise = Field(
383 default=SourcePiecewise(),
384 description="Definition of piecewise current source parameters.")
385 quench_propagation: Optional[Literal['2Dx1D','full']] = Field(
386 default = "full",
387 description = 'Enables to have a variable length for the ecliq implementation, different from the full magnet length. It only affects the Thermal Behaviour of the model.')
388 quench_prop_model: Optional[Literal['Wilson','Ts']] = Field(
389 default = "Ts",
390 description = 'Selects the model used for the material properties of the quench propagation. "Wilson" uses a scaled cv with a function of T_bath and Ts and Ts uses the cv at Ts.')
391 NZPV_multiplier: Optional[float] = Field(
392 default = 1.0,
393 description = 'Factor that multiplies the Normal Zone Propagation Velocity')
394 N_units: Optional[List[int]] = Field(
395 default = [],
396 description= 'Number of E-CLIQ units along the magnet length per ecliq coil. It must be an odd number for symmetry reasons.')
397 h_ecliq: Optional[List[float]] = Field(
398 default = [],
399 description = 'Spacing between the ecliq coils along the magnet length (m).')
400 l_ecliq: Optional[List[float]] = Field(
401 default = [],
402 description = 'length of the ecliq coils along the magnet length (m).')
403 L_ecliq_offset: Optional[List[float]] = Field(
404 default = [],
405 description = 'Offset of the quench heater strip from the referrence point located at the middle of the magnet length. Positive values move the quench heater towards higher z values (move quench heater strip towards the front ofthe magnet).')
407class QuenchDetection(BaseModel):
408 """
409 Level 2: Class for FiQuS
410 """
412 voltage_thresholds: Optional[List[float]] = Field(
413 default=None,
414 title="List of quench detection voltage thresholds",
415 description="Voltage thresholds for quench detection. The quench detection will be triggered when the voltage exceeds these thresholds continuously for a time larger than the discrimination time.",
416 )
418 discrimination_times: Optional[List[float]] = Field(
419 default=None,
420 title="List of quench detection discrimination times",
421 description="Discrimination times for quench detection. The quench detection will be triggered when the voltage exceeds the thresholds continuously for a time larger than these discrimination times.",
422 )
424 voltage_tap_pairs: Optional[List[List[int]]] = Field(
425 default=None,
426 title="List of quench detection voltage tap pairs",
427 description="Voltage tap pairs for quench detection. The voltage difference between these pairs will be used for quench detection.",
428 )
430class QuenchProtection(BaseModel):
431 """
432 Level 1: Class for quench protection
433 """
434 Energy_Extraction: EnergyExtraction = EnergyExtraction()
435 Quench_Heaters: QuenchHeater = QuenchHeater()
436 CLIQ: CLIQ_Class = CLIQ_Class()
437 ESC: ESC_Class = ESC_Class()
438 FQPCs: FQPCs_Class = FQPCs_Class()
439 E_CLIQ: E_CLIQ_Class = E_CLIQ_Class()