1 /*
2  * Copyright (c) 2019-2020 Kevin Townsend (KTOWN)
3  * Copyright (c) 2021 Marti Riba Pons
4  *
5  * SPDX-License-Identifier: Apache-2.0
6  */
7 
8 /**
9  * @addtogroup ELECTRICITY Electricity
10  *
11  * @brief Electricity functions.
12  *
13  * \ingroup PHYSICS
14  *  @{ */
15 
16 /**
17  * @file
18  * @brief API header file for electricity in zscilib.
19  *
20  * This file contains the zscilib electricity APIs
21  */
22 
23 #ifndef ZEPHYR_INCLUDE_ZSL_ELECTRICITY_H_
24 #define ZEPHYR_INCLUDE_ZSL_ELECTRICITY_H_
25 
26 #include <zsl/zsl.h>
27 #include <zsl/vectors.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /**
34  * @brief Calculates the electric current based on the charge (q) that crosses
35  * 		  a transversal area during a period of time (t).
36  *
37  * @param q    Charge in coulombs.
38  * @param t    Time in seconds.
39  * @param i    Pointer to the calculated electric current in amperes. Will be
40  * 			   set to NAN if the time is negative ir zero.
41  *
42  * @return 0 on success, and non-zero error code on failure.
43  */
44 int zsl_phy_elcty_current(zsl_real_t q, zsl_real_t t, zsl_real_t *i);
45 
46 /**
47  * @brief Calculates the equivalent resistance of a set of resistors in series.
48  *
49  * @param v    Vector whose coefficients are the resistances in Ohms of the
50  * 			   resistors in series.
51  * @param r    Pointer to the equivalent resistance in Ohms. Will be set to NAN
52  *             if any of the input resistances is negative.
53  *
54  * @return 0 on success, and non-zero error code on failure.
55  */
56 int zsl_phy_elcty_res_series(struct zsl_vec *v, zsl_real_t *r);
57 
58 /**
59  * @brief Calculates the equivalent resistance of a set of resistors
60  * 		  in parallel.
61  *
62  * @param v    Vector whose coefficients are the resistances in Ohms of the
63  * 			   resistors in parallel.
64  * @param r    Pointer to the equivalent resistance in Ohms. Will be set to NAN
65  *             if any of the input resistances is negative or zero.
66  *
67  * @return 0 on success, and non-zero error code on failure.
68  */
69 int zsl_phy_elcty_res_parallel(struct zsl_vec *v, zsl_real_t *r);
70 
71 /**
72  * @brief Calculates the equivalent capacitance of a set of capacitors
73  * 		  in series.
74  *
75  * @param v    Vector whose coefficients are the capacitances in farads of the
76  * 			   capacitors in series.
77  * @param c    Pointer to the equivalent capacitance in farads. Will be set to
78  *             NAN if any of the input capacitances is negative or zero.
79  *
80  * @return 0 on success, and non-zero error code on failure.
81  */
82 int zsl_phy_elcty_cap_series(struct zsl_vec *v, zsl_real_t *c);
83 
84 /**
85  * @brief Calculates the equivalent capacitance of a set of capacitors
86  * 		  in parallels.
87  *
88  * @param v    Vector whose coefficients are the capacitances in farads of the
89  * 			   capacitors in parallel.
90  * @param c    Pointer to the equivalent capacitance in farads. Will be set to
91  *             NAN if any of the input capacitances is negative.
92  *
93  * @return 0 on success, and non-zero error code on failure.
94  */
95 int zsl_phy_elcty_cap_parallel(struct zsl_vec *v, zsl_real_t *c);
96 
97 /**
98  * @brief Calculates the resistivity of a uniform piece of material of area
99  * 		  section 'a', length 'l' and resistance 'r'.
100  *
101  * @param r     Resistance of the material in ohms.
102  * @param a     Area section in square meters.
103  * @param l     Length in meters.
104  * @param rty   Pointer to the resistivity in ohms times meters. Will be set to
105  *              NAN if the area section, length or resistance are negative, or
106  *              if l = 0.
107  *
108  * @return 0 on success, and non-zero error code on failure.
109  */
110 int zsl_phy_elcty_resistivity(zsl_real_t r, zsl_real_t a, zsl_real_t l,
111 			      zsl_real_t *rty);
112 
113 /**
114  * @brief Calculates the voltage between two points in an electrical circiut
115  * 	      based on the electric current (i) and resistance (r) using Ohm's law.
116  *
117  * @param i    Electric current in amperes.
118  * @param r    Resistance in ohms.
119  * @param v    Pointer to the calculated voltage in volts. Will be set to NAN
120  *             if the resistance is negative.
121  *
122  * @return 0 on success, and non-zero error code on failure.
123  */
124 int zsl_phy_elcty_ohm_law(zsl_real_t i, zsl_real_t r, zsl_real_t *v);
125 
126 /**
127  * @brief Calculates the electric power based on the voltage (v) and electric
128  * 		  current (i).
129  *
130  * @param v    Voltage in volts.
131  * @param i    Electric current in amperes.
132  * @param p    Pointer to the output electric power in watts.
133  *
134  * @return  0 if everything executed correctly, otherwise an appropriate
135  *          error code.
136  */
137 int zsl_phy_elcty_power_vi(zsl_real_t v, zsl_real_t i, zsl_real_t *p);
138 
139 /**
140  * @brief Calculates the electric power based on the electric current (i) and
141  * 		  the resistance (r).
142  *
143  * @param i    Electric current in amperes.
144  * @param r    Resistance in ohms.
145  * @param p    Pointer to the output electric power in watts. Will be set to
146  * 			   NAN if the resistance is negative.
147  *
148  * @return  0 on success, and non-zero error code on failure.
149  */
150 int zsl_phy_elcty_power_ir(zsl_real_t i, zsl_real_t r, zsl_real_t *p);
151 
152 /**
153  * @brief Calculates the electric power based on the voltage (v) and the
154  * 		  resistance (r).
155  *
156  * @param v    Voltage in volts.
157  * @param r    Resistance in ohms.
158  * @param p    Pointer to the output electric power in watts. Will be set to
159  * 			   NAN if the resistance is negative or zero.
160  *
161  * @return  0 on success, and non-zero error code on failure.
162  */
163 int zsl_phy_elcty_power_vr(zsl_real_t v, zsl_real_t r, zsl_real_t *p);
164 
165 #ifdef __cplusplus
166 }
167 #endif
168 
169 #endif /* ZEPHYR_INCLUDE_ZSL_ELECTRICITY_H_ */
170 
171 /** @} */ /* End of electricity group */
172