1 /*
2  * Copyright (c) 2019-2020 Kevin Townsend (KTOWN)
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 /**
8  * @addtogroup ELECTRICAL_COMPS Electrical components.
9  *
10  * @brief Electrical component functions.
11  *
12  * @ingroup PHYSICS
13  *  @{ */
14 
15 /**
16  * @file
17  * @brief API header file for electrical components in zscilib.
18  *
19  * This file contains the zscilib electrical component APIs
20  */
21 
22 #ifndef ZEPHYR_INCLUDE_ZSL_ELEC_COMPS_H_
23 #define ZEPHYR_INCLUDE_ZSL_ELEC_COMPS_H_
24 
25 #include <zsl/zsl.h>
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 /**
32  * @brief Calculates capacitance in farads based on charge (q) and voltage (v).
33  *
34  * @param q     Charge in coulombs.
35  * @param v     Voltage in volts.
36  * @param c     Pointer to the output capacitance in farads. Will be set to
37  *              NAN if v = 0.
38  *
39  * @return 0 if everything executed properly, error code on failure.
40  */
41 int zsl_phy_ecmp_capac_cpv(zsl_real_t q, zsl_real_t v, zsl_real_t *c);
42 
43 /**
44  * @brief Calculates capacitance in farads based on the permitivity
45  *        of freespace multiplied by area (a) and divided by distance (d).
46  *        i.e.: C = E (A / D) where E = 8.85 x 10^-12 farad per meter (F/m).
47  *
48  * This function can be used to calculate the value of a parallel plate
49  * capacitor, consisting of two metallic plates of area a, separated by a
50  * vacuum with a gap of d.
51  *
52  * @param a     Area in square meters.
53  * @param d     Distance in meters.
54  * @param c     Pointer to the output capacitance in farads. Will be set to
55  *              NAN if d = 0.
56  *
57  * @return 0 if everything executed properly, error code on failure.
58  */
59 int zsl_phy_ecmp_capac_ad(zsl_real_t a, zsl_real_t d, zsl_real_t *c);
60 
61 /**
62  * @brief Calculates the energy in joules of a capacitor of capacitance 'c' and
63  *        voltage 'v'.
64  *
65  * @param c     Capacitance in farads.
66  * @param v     Voltage in volts.
67  * @param u     Pointer to the output energy in joules.
68  *
69  * @return 0 if everything executed properly, error code on failure.
70  */
71 int zsl_phy_ecmp_ener_capac(zsl_real_t c, zsl_real_t v, zsl_real_t *u);
72 
73 /**
74  * @brief Calculates the energy in joules of an inductor of inductance 'l' and
75  *        electric current 'i'.
76  *
77  * @param l     Inductance in henrys.
78  * @param i     Electric current in amperes.
79  * @param u     Pointer to the output energy in joules.
80  *
81  * @return 0 if everything executed properly, error code on failure.
82  */
83 int zsl_phy_ecmp_ener_induc(zsl_real_t l, zsl_real_t i, zsl_real_t *u);
84 
85 /**
86  * @brief Calculates the output voltage in volts in a two-coil based
87  *        transformer given the number of turns on each coil and the input
88  *        voltage.
89  *
90  * @param t1     Number of turns of the input coil.
91  * @param v1     Voltage in the input coil, in volts.
92  * @param t2     Number of turns of the output coil.
93  * @param v2     Pointer to the output voltage in the output coil in volts. Will
94  *               be set to NAN if any of the number of turns is negative.
95  *
96  * @return 0 if everything executed properly, error code on failure.
97  */
98 int zsl_phy_ecmp_trans(uint8_t t1, zsl_real_t v1, uint8_t t2, zsl_real_t *v2);
99 
100 /**
101  * @brief Calculates the total voltage of a RCL circuit based on the voltage in
102  *        the resistance (vr), in the inductor (vl) and in the capacitor (vc).
103  *
104  * @param vr    Voltage in the resistance.
105  * @param vl    Voltage in the inductor.
106  * @param vc    Voltage in the capacitor.
107  * @param v     Pointer to the total voltage in volts.
108  *
109  * @return 0 if everything executed properly, error code on failure.
110  */
111 int zsl_phy_ecmp_rlc_volt(zsl_real_t vr, zsl_real_t vl, zsl_real_t vc,
112 			  zsl_real_t *v);
113 
114 /**
115  * @brief Calculates the electric current of a capacitor in a RC circuit
116  *        during its charging phase.
117  *
118  * @param r     Resistance in ohms.
119  * @param c     Capacitance in farads.
120  * @param t     Time in seconds.
121  * @param i0    Initial current of the capacitor in amperes.
122  * @param i     Pointer to the output electric current in amperes. Will be set
123  *              to NAN if r * c is less or equal than zero or if the time or the
124  *              initial current are negavive.
125  *
126  * @return 0 if everything executed properly, error code on failure.
127  */
128 int zsl_phy_ecmp_rc_charg_i(zsl_real_t r, zsl_real_t c, zsl_real_t t,
129 			    zsl_real_t i0, zsl_real_t *i);
130 
131 /**
132  * @brief Calculates the electric charge in coulombs of a capacitor in a RC
133  *        circuit during its charging phase.
134  *
135  * @param r     Resistance in ohms.
136  * @param c     Capacitance in farads.
137  * @param t     Time in seconds.
138  * @param q0    Initial charge of the capacitor in coulombs.
139  * @param q     Pointer to the output electric charge in coulombs. Will be set
140  *              to NAN if r * c is less or equal than zero or if the time or the
141  *              initial charge are negavive.
142  *
143  * @return 0 if everything executed properly, error code on failure.
144  */
145 int zsl_phy_ecmp_rc_charg_q(zsl_real_t r, zsl_real_t c, zsl_real_t t,
146 			    zsl_real_t q0, zsl_real_t *q);
147 
148 /**
149  * @brief Calculates the electric current of a capacitor in a RC circuit
150  *        during its discharging phase.
151  *
152  * @param r     Resistance in ohms.
153  * @param c     Capacitance in farads.
154  * @param t     Time in seconds.
155  * @param i0    Initial current of the capacitor in amperes.
156  * @param i     Pointer to the output electric current in amperes. Will be set
157  *              to NAN if r * c is less or equal than zero or if the time or the
158  *              initial current are negavive.
159  *
160  * @return 0 if everything executed properly, error code on failure.
161  */
162 int zsl_phy_ecmp_rc_discharg_i(zsl_real_t r, zsl_real_t c, zsl_real_t t,
163 			       zsl_real_t i0, zsl_real_t *i);
164 
165 /**
166  * @brief Calculates the electric charge in coulombs of a capacitor in a RC
167  *        circuit during its discharging phase.
168  *
169  * @param r     Resistance in ohms.
170  * @param c     Capacitance in farads.
171  * @param t     Time in seconds.
172  * @param q0    Initial charge of the capacitor in coulombs.
173  * @param q     Pointer to the output electric charge in coulombs. Will be set
174  *              to NAN if r * c is less or equal than zero or if the time or the
175  *              initial charge are negavive.
176  *
177  * @return 0 if everything executed properly, error code on failure.
178  */
179 int zsl_phy_ecmp_rc_discharg_q(zsl_real_t r, zsl_real_t c, zsl_real_t t,
180 			       zsl_real_t q0, zsl_real_t *q);
181 
182 /**
183  * @brief Calculates the electric current in amperes of a RL circuit in time.
184  *
185  * @param r     Resistance in ohms.
186  * @param l     Inductance in henrys.
187  * @param t     Time in seconds.
188  * @param i0    Initial current of the capacitor in amperes.
189  * @param i     Pointer to the output electric current in amperes. Will be set
190  *              to NAN the time, the inductance, the resistance or the initial
191  *              current are negavive.
192  *
193  * @return 0 if everything executed properly, error code on failure.
194  */
195 int zsl_phy_ecmp_rl_current(zsl_real_t r, zsl_real_t l, zsl_real_t t,
196 			    zsl_real_t i0, zsl_real_t *i);
197 
198 #ifdef __cplusplus
199 }
200 #endif
201 
202 #endif /* ZEPHYR_INCLUDE_ZSL_ELEC_COMPS_H_ */
203 
204 /** @} */ /* End of electrical components group */
205