Re-organize math/series (#5044)

* added harmonic mean

* Update maths/series/harmonic_mean.py

Updated the write-up of reference given in the code.

Co-authored-by: John Law <johnlaw.po@gmail.com>

* changes in arithmetic and geometric mean code

* mean and series added in a single file

Co-authored-by: John Law <johnlaw.po@gmail.com>

maths/series/arithmetic.py

@@ -1,20 +1,35 @@
 """
-ARITHMETIC MEAN : https://en.wikipedia.org/wiki/Arithmetic_mean
+Arithmetic mean
+Reference: https://en.wikipedia.org/wiki/Arithmetic_mean
 
+Arithmetic series
+Reference: https://en.wikipedia.org/wiki/Arithmetic_series
+(The URL above will redirect you to arithmetic progression)
 """
 
 
 def is_arithmetic_series(series: list) -> bool:
     """
     checking whether the input series is arithmetic series or not
-
     >>> is_arithmetic_series([2, 4, 6])
     True
     >>> is_arithmetic_series([3, 6, 12, 24])
     False
     >>> is_arithmetic_series([1, 2, 3])
     True
+    >>> is_arithmetic_series(4)
+    Traceback (most recent call last):
+        ...
+    ValueError: Input series is not valid, valid series - [2, 4, 6]
+    >>> is_arithmetic_series([])
+    Traceback (most recent call last):
+        ...
+    ValueError: Input list must be a non empty list
     """
+    if not isinstance(series, list):
+        raise ValueError("Input series is not valid, valid series - [2, 4, 6]")
+    if len(series) == 0:
+        raise ValueError("Input list must be a non empty list")
     if len(series) == 1:
         return True
     common_diff = series[1] - series[0]
@@ -37,9 +52,7 @@ def arithmetic_mean(series: list) -> float:
         ...
     ValueError: Input series is not valid, valid series - [2, 4, 6]
     >>> arithmetic_mean([4, 8, 1])
-    Traceback (most recent call last):
-        ...
-    ValueError: Input list is not an arithmetic series
+    4.333333333333333
     >>> arithmetic_mean([1, 2, 3])
     2.0
     >>> arithmetic_mean([])
@@ -52,8 +65,6 @@ def arithmetic_mean(series: list) -> float:
         raise ValueError("Input series is not valid, valid series - [2, 4, 6]")
     if len(series) == 0:
         raise ValueError("Input list must be a non empty list")
-    if not is_arithmetic_series(series):
-        raise ValueError("Input list is not an arithmetic series")
     answer = 0
     for val in series:
         answer += val

maths/series/geometric.py

@@ -1,12 +1,15 @@
 """
-GEOMETRIC MEAN :  https://en.wikipedia.org/wiki/Geometric_mean
+Geometric Mean
+Reference :  https://en.wikipedia.org/wiki/Geometric_mean
+
+Geometric series
+Reference: https://en.wikipedia.org/wiki/Geometric_series
 """
 
 
 def is_geometric_series(series: list) -> bool:
     """
     checking whether the input series is geometric series or not
-
     >>> is_geometric_series([2, 4, 8])
     True
     >>> is_geometric_series([3, 6, 12, 24])
@@ -15,8 +18,19 @@ def is_geometric_series(series: list) -> bool:
     False
     >>> is_geometric_series([0, 0, 3])
     False
-
+    >>> is_geometric_series([])
+    Traceback (most recent call last):
+        ...
+    ValueError: Input list must be a non empty list
+    >>> is_geometric_series(4)
+    Traceback (most recent call last):
+        ...
+    ValueError: Input series is not valid, valid series - [2, 4, 8]
     """
+    if not isinstance(series, list):
+        raise ValueError("Input series is not valid, valid series - [2, 4, 8]")
+    if len(series) == 0:
+        raise ValueError("Input list must be a non empty list")
     if len(series) == 1:
         return True
     try:
@@ -44,13 +58,9 @@ def geometric_mean(series: list) -> float:
         ...
     ValueError: Input series is not valid, valid series - [2, 4, 8]
     >>> geometric_mean([1, 2, 3])
-    Traceback (most recent call last):
-        ...
-    ValueError: Input list is not a geometric series
+    1.8171205928321397
     >>> geometric_mean([0, 2, 3])
-    Traceback (most recent call last):
-        ...
-    ValueError: Input list is not a geometric series
+    0.0
     >>> geometric_mean([])
     Traceback (most recent call last):
         ...
@@ -61,8 +71,6 @@ def geometric_mean(series: list) -> float:
         raise ValueError("Input series is not valid, valid series - [2, 4, 8]")
     if len(series) == 0:
         raise ValueError("Input list must be a non empty list")
-    if not is_geometric_series(series):
-        raise ValueError("Input list is not a geometric series")
     answer = 1
     for value in series:
         answer *= value

maths/series/harmonic.py

@@ -0,0 +1,92 @@
+"""
+Harmonic mean
+Reference: https://en.wikipedia.org/wiki/Harmonic_mean
+
+Harmonic series
+Reference: https://en.wikipedia.org/wiki/Harmonic_series(mathematics)
+"""
+
+
+def is_harmonic_series(series: list) -> bool:
+    """
+    checking whether the input series is arithmetic series or not
+    >>> is_harmonic_series([ 1, 2/3, 1/2, 2/5, 1/3])
+    True
+    >>> is_harmonic_series([ 1, 2/3, 2/5, 1/3])
+    False
+    >>> is_harmonic_series([1, 2, 3])
+    False
+    >>> is_harmonic_series([1/2, 1/3, 1/4])
+    True
+    >>> is_harmonic_series([2/5, 2/10, 2/15, 2/20, 2/25])
+    True
+    >>> is_harmonic_series(4)
+    Traceback (most recent call last):
+        ...
+    ValueError: Input series is not valid, valid series - [1, 2/3, 2]
+    >>> is_harmonic_series([])
+    Traceback (most recent call last):
+        ...
+    ValueError: Input list must be a non empty list
+    >>> is_harmonic_series([0])
+    Traceback (most recent call last):
+        ...
+    ValueError: Input series cannot have 0 as an element
+    >>> is_harmonic_series([1,2,0,6])
+    Traceback (most recent call last):
+        ...
+    ValueError: Input series cannot have 0 as an element
+    """
+    if not isinstance(series, list):
+        raise ValueError("Input series is not valid, valid series - [1, 2/3, 2]")
+    if len(series) == 0:
+        raise ValueError("Input list must be a non empty list")
+    if len(series) == 1 and series[0] != 0:
+        return True
+    rec_series = []
+    series_len = len(series)
+    for i in range(0, series_len):
+        if series[i] == 0:
+            raise ValueError("Input series cannot have 0 as an element")
+        rec_series.append(1 / series[i])
+    common_diff = rec_series[1] - rec_series[0]
+    for index in range(2, series_len):
+        if rec_series[index] - rec_series[index - 1] != common_diff:
+            return False
+    return True
+
+
+def harmonic_mean(series: list) -> float:
+    """
+    return the harmonic mean of series
+
+    >>> harmonic_mean([1, 4, 4])
+    2.0
+    >>> harmonic_mean([3, 6, 9, 12])
+    5.759999999999999
+    >>> harmonic_mean(4)
+    Traceback (most recent call last):
+        ...
+    ValueError: Input series is not valid, valid series - [2, 4, 6]
+    >>> harmonic_mean([1, 2, 3])
+    1.6363636363636365
+    >>> harmonic_mean([])
+    Traceback (most recent call last):
+        ...
+    ValueError: Input list must be a non empty list
+
+    """
+    if not isinstance(series, list):
+        raise ValueError("Input series is not valid, valid series - [2, 4, 6]")
+    if len(series) == 0:
+        raise ValueError("Input list must be a non empty list")
+    answer = 0
+    for val in series:
+        answer += 1 / val
+    return len(series) / answer
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()