write readme

Author: lunaluxie

readme.md

@@ -1,55 +1,151 @@
-# Funkypy
+# LuxTools
+> A collection of tools and utilities that I often use in my work.
 
-A collection of functional programming utilities for Python.
+## Features
 
+- **[Scientific](#scientific)**
+  - [Error propagation](#error-propagation) for numerical calculations
+  - [Pretty printing](#numeric-result-formatting) of numerical results with uncertainties
+- **[Functional](#functional)**
+  - [Function composition](#function-composition) utilities
+  - [Partial function](#partial-application) application
+  - [Overload function](#overload-function-definitions) definitions
 
+## Installation
+
+```bash
+pip install luxtools
 ```
-partial
-```
 
-Okay so i think I understand the problem of multiple partial:
-- @partial return a function, and it's that function we edit to apply it. 
-- It should return the function we get to return the function that can the be partialled every time we try again. 
-    - maybe upon successful call 
-    - or maybe should give up and use functools.partial. 
+## Usage
+
+### Scientific
 
+#### Error Propagation
 
+```python
+import torch
+from luxtools import get_error
 
-# Significant Figures
+# Create tensors with uncertainties
+x = torch.tensor([1.0, 3.0], dtype=torch.float32, requires_grad=True)
+x.sigma = torch.tensor([0.1, 0.2], dtype=torch.float32)
 
-## Installation
-Navigate to the root directory of the repository and run the following command:
+y = torch.tensor([2.0, 4.0], dtype=torch.float32, requires_grad=True)
+y = Variable(y, torch.tensor([0.2, 0.3]))
 
-```bash
-pip install -e . 
+# Perform calculations
+f = x * y
+
+# Get propagated error
+error = get_error(f)
+# tensor([0.2828, 1.2042])
 ```
 
-## Usage
+#### Numeric Result Formatting
+
 ```python
-from significant_figures import NumericResult
+from luxtools import NumericResult
 
-result = NumericResult(value=1.2345, uncertainty=0.01, unit='m')
+# Create a measurement with uncertainty
+result = NumericResult(1.234, 0.193)
+print(result)
+# (1.2 ± 0.2)
 
+# Scientific notation
+result = NumericResult(234.23424, 10)
 print(result)
-# Output: (1.23 ± 0.01) m
+# (2.3 ± 0.1)*10^(2)
+
+# LaTeX output
+print(result.latex())
+# (2.3 \pm 0.1)\cdot 10^{2}
+```
+
+### Functional
+
+#### Function Composition
+
+```python
+from luxtools import chain
+
+# Compose functions
+f = lambda x: x + 1
+g = lambda x: x * 2
+h = lambda x: x ** 2
+
+# Create a new function that applies f, then g, then h
+composed = chain(f, g, h)
 
-print(result.latex(delimiter=""))
-# Output: (1.23 \\pm 0.01) m
+result = composed(3)  # ((3 + 1) * 2) ** 2 = 64
 ```
 
+#### Partial Application
+Allows you to partially apply arguments to a function, creating a new function with fewer arguments. See [article](https://lunalux.io/functional-programming-in-python/better-currying-in-python/) for discussion.
+
+```python
+from luxtools import partial
+
+@partial
+def greet(greeting, name):
+    return f"{greeting}, {name}!"
+
+# Create a new function with 'Hello' fixed as the greeting
+say_hello = greet("Hello")
+
+result = say_hello("World")  # "Hello, World!"
+```
+
+#### Overload function definitions
+
+Allows you to have multiple function definitions for the same function name. 
+It uses typehints to determine which function to call. See [article](https://lunalux.io/functional-programming-in-python/overloading-functions-in-python/) for discussion.
+
+```python
+from luxtools import overload
+
+class Email:
+    def __init__(self, email: str):
+        self.email = email
+
+    def __str__(self) -> str:
+        return self.email
+
+
+class PhoneNumber:
+    def __init__(self, phone_number: str):
+        self.phone_number = phone_number
+
+    def __str__(self) -> str:
+        return self.phone_number
+
+
+@overload
+def get_user(email: Email):
+    print("Email:", email)
+    return email
+
+
+@overload
+def get_user(phone_number: PhoneNumber):
+    print("Phone:", phone_number)
+    return phone_number
+
+get_user(Email("test@example.com"))  # prints: Email: test@example.com
+get_user(PhoneNumber("123-456-789"))  # prints: Phone: 123-456-789
+```
+
+Caveat, if the function is defined in a non-global scope such as a class, or inside a function, then you need to pass the local scope to the decorator. 
+
+```python
+def local_scope():
+    @overload(scope=locals())
+    def get_user(email: Email):
+        print("Email:", email)
+
+    @overload(scope=locals())
+    def get_user(phone_number: PhoneNumber):
+        print("Phone:", phone_number)
+```
 
-## Examples
-```Python
-Value, Uncertainty, expected result. 
-(1e-4, 1e-5, "(1.0 +/- 0.1)*10^(-4)"),
-(1, 0.1, "(1.0 +/- 0.1)"),
-(1.234, 0.193, "(1.2 +/- 0.2)"),
-(0.1, 1, "(0 +/- 1)"),
-(234.23424,10, "(2.3 +/- 0.1)*10^(2)"),
-(0, 0, "(0 +/- 0)"),
-(10, 0, "(1.0 +/- 0.0)*10^(1)"),
-(0, 10, "(0 +/- 1)*10^(1)"),
-(0.123456789, 0.987654321, "(1 +/- 10)*10^(-1)"),
-(123456789, 987654321, "(1 +/- 10)*10^(8)"),
-(1.23456789e-9, 9.87654321e-11, "(1.23 +/- 0.10)*10^(-9)"),
-```
+This is necessary because the parent stack frame doesn't exist inside the `overload` function, so it has to be passed explicitly. See [tests](test/functional/test_overload.py).