Merge pull request #33 from MIT-Emerging-Talent/challenge-3-the-tribo…

…nacci-sequence

Challenge 3 the tribonacci sequence

solutions/tests/test_tribonacci_sequence.py

@@ -0,0 +1,57 @@
+"""
+Unit tests for the tribonacci function.
+
+This module tests the tribonacci function to ensure it calculates the nth Tribonacci number correctly.
+The test cases include:
+    - Base cases (e.g., T(0), T(1), T(2)).
+    - Standard cases (e.g., T(5), T(10)).
+    - Edge cases (e.g., large n values).
+    - Defensive assertions for invalid inputs.
+
+Created on: 01/01/2025
+Author: Ana Isabel Murillo
+"""
+
+import unittest
+
+from solutions.the_tribonacci_sequence.main import tribonacci
+
+
+class TestTribonacci(unittest.TestCase):
+    """Test suite for the tribonacci function."""
+
+    def test_base_cases(self):
+        """Test the base cases."""
+        self.assertEqual(tribonacci(0), 0)  # Base case T(0)
+        self.assertEqual(tribonacci(1), 1)  # Base case T(1)
+        self.assertEqual(tribonacci(2), 1)  # Base case T(2)
+
+        self.assertIsInstance(tribonacci(0), int, "output should be an integer")
+        self.assertIsInstance(tribonacci(1), int, "Output should be an integer.")
+        self.assertIsInstance(tribonacci(2), int, "Output should be an integer.")
+
+    def test_standard_cases(self):
+        """Test standard cases."""
+        self.assertEqual(tribonacci(3), 2)  # 0, 1, 1, 2
+        self.assertEqual(tribonacci(4), 4)  # 0, 1, 1, 2, 4
+        self.assertEqual(tribonacci(5), 7)  # 0, 1, 1, 2, 4, 7
+        self.assertEqual(tribonacci(6), 13)  # 0, 1, 1, 2, 4, 7, 13
+
+        self.assertIsInstance(tribonacci(3), int, "Output should be an integer.")
+        self.assertIsInstance(tribonacci(4), int, "Output should be an integer.")
+        self.assertIsInstance(tribonacci(5), int, "Output should be an integer.")
+        self.assertIsInstance(tribonacci(6), int, "Output should be an integer.")
+
+    def test_large_values(self):
+        """Test for larger values of n."""
+        self.assertEqual(tribonacci(10), 149)  # Verify correct calculation for T(10)
+        self.assertEqual(tribonacci(15), 3136)  # Verify correct calculation for T(15)
+
+        self.assertIsInstance(tribonacci(10), int, "Output should be an integer.")
+        self.assertIsInstance(tribonacci(15), int, "Output should be an integer.")
+
+    def test_edge_cases(self):
+        """Test edge cases."""
+        self.assertEqual(tribonacci(30), 29249425)  # Large n value
+
+        self.assertIsInstance(tribonacci(30), int, "Output should be an integer.")

solutions/the_tribonacci_sequence/README.md

@@ -0,0 +1,78 @@
+# Tribonacci Sequence Challenge
+
+## Overview
+
+This challenge involves calculating the nth number in the **Tribonacci sequence**.
+
+- The first three numbers are defined as:
+  - T(0) = 0, T(1) = 1, T(2) = 1.
+- For n ≥ 3, the sequence is defined as:
+  - T(n) = T(n-1) + T(n-2) + T(n-3).
+
+The objective is to write an efficient function to compute the nth Tribonacci number
+while handling edge cases and invalid inputs.
+
+---
+
+## Project Contents
+
+### Main Script
+
+The `main.py` file contains the implementation of the `tribonacci` function,
+which calculates the nth Tribonacci number.
+
+**Features**:
+
+- Computes the nth Tribonacci number iteratively for optimal performance.
+- Handles invalid inputs, such as negative values, by raising a `ValueError`.
+- Includes docstrings with detailed explanations and usage examples.
+
+**Example usage**:
+
+```python
+>>> from solutions.the_tribonacci_sequence.main import tribonacci
+>>> tribonacci(5)
+7
+>>> tribonacci(10)
+149
+```
+
+### Unit Tests
+
+The `test_tribonacci.py` file provides a comprehensive suite of tests
+for the `tribonacci` function using Python’s built-in `unittest` framework.
+
+### Test Coverage
+
+1. **Base Cases**:
+   - Verifies the initial values:
+     - T(0) = 0
+     - T(1) = 1
+     - T(2) = 1
+
+2. **Standard Cases**:
+   - Tests for typical Tribonacci calculations, such as:
+     - T(5) = 7
+     - T(10) = 149
+
+3. **Edge Cases**:
+   - Handles larger values of `n`:
+     - T(30) = 29249425
+
+4. **Defensive Assertions**:
+   - Ensures the function raises a `ValueError` for invalid inputs,
+   such as negative values (`n < 0`).
+
+---
+
+## How to Run the Code
+
+### 1. Running the Function
+
+The `tribonacci` function can be imported and executed as follows:
+
+```python
+from solutions.the_tribonacci_sequence.main import tribonacci
+
+# Calculate the 7th Tribonacci number
+print(tribonacci(7))  # Output: 24

solutions/the_tribonacci_sequence/main.py

@@ -0,0 +1,51 @@
+def tribonacci(n: int) -> int:
+    """
+        Calculate the nth Tribonacci number.
+        The objective is to write an efficient function to compute the nth Tribonacci number while handling edge cases and invalid inputs.
+
+    The Tribonacci sequence starts as follows:
+    T(0) = 0, T(1) = 1, T(2) = 1, and for n >= 3,
+    T(n) = T(n-1) + T(n-2) + T(n-3).
+
+    This function utilizes an iterative approach to calculate the Tribonacci sequence.
+    It maintains a list of the last three calculated numbers and iteratively updates this list
+    by adding the sum of the three numbers to the end, effectively simulating the Tribonacci sequence's definition.
+    This iterative method provides efficient calculation without the overhead of recursive function calls.
+
+    Returns the first n numbers of the tribonacci sequence.
+
+    Args:
+
+        n (int): A non-negative integer representing the index of the Tribonacci number to calculate.
+
+    Returns:
+        int: The nth Tribonacci number.
+
+    Raises:
+        ValueError: If n is negative.
+
+    Examples:
+        >>> tribonacci(0)
+        0
+        >>> tribonacci(2)
+        1
+        >>> tribonacci(5)
+        7
+
+        Created on 1/01/2025
+    Author: Ana Isabel Murillo
+    """
+
+    if n < 0:
+        raise ValueError("Index 'n' must be a non-negative integer.")
+    if n == 0:
+        return 0
+    elif n == 1 or n == 2:
+        return 1
+
+    a, b, c = 0, 1, 1
+
+    for _ in range(3, n + 1):
+        a, b, c = b, c, a + b + c
+
+    return c