mathhunt 0.5.1
Toolkit for math calculations.
License: MIT
Requires Python: >=3.6

# Mathhunt Library

Mathhunt is a lightweight Python library designed for quick and efficient mathematical computations. It provides functions for calculating the volume and area of various geometric shapes, as well as distances between points in a Cartesian coordinate system.

## Table of Contents

- [Installation](#installation)
- [Modules](#modules)
  - [Geometry](#geometry)
  - [Mathematical-functions](#mathematical-functions)
  - [Visualization](#visualization)
  - [Probability](#probability)
  - [Logic](#logic)


## Installation

```cmd
pip install mathhunt
```

## Usage

You should import module that you need to use from mathhunt

For example you need to use sinus function. You should situate 

```python
from mathhunt import functions

print(functions.sinus(45, "deg"))
```

Here you can see 2 arguments

## Geometry
### Volume-calculation

- The volume function calculates the volume of various 3D shapes  based on the provided shape type and corresponding metrics. It supports multiple geometric shapes and ensures input validation for accurate calculations.

**Parameters**
```python
*args (float)
```
: A variable-length argument list representing the necessary metrics for the specified shape (e.g., radius, height, side length). The number of arguments required depends on the shape type.

```python
type (str)
```
: A string that specifies the type of shape for which the volume is to be calculated. Supported types include:

'parallelepiped'
'cube'
'cylinder'
'sphere'
'cone'
'pyramid'
'tetrahedron'
'octahedron'
'icosahedron'
Returns
float: The calculated volume of the specified shape.
Raises
TypeError:

If any of the input metrics (*args) are not numbers (either int or float).
If the type parameter is not a string.
ValueError:

If the specified shape type is invalid (not one of the supported types).
If the number of arguments does not match the expected count for the specified shape type.
If any of the provided metrics are non-positive (less than or equal to zero).

**Examples of usage**

> Calculate the volume of a cube with side length 3
volume_cube = volume(3, type='cube')  # Returns: 27.0

> Calculate the volume of a cylinder with radius 2 and height 5
volume_cylinder = volume(2, 5, type='cylinder')  # Returns: 25.12

> Calculate the volume of a sphere with radius 4
volume_sphere = volume(4, type='sphere')  # Returns: 268.08

> Invalid usage example
```python
volume_invalid = volume(2, 3, type='invalid_shape')
```
Raises ValueError

### Square-calculation
`square(*args: float, type: str) -> float`  
Calculate the **area of various 2D shapes** (and surface area of a sphere).  

**Arguments**:  
- `*args` *(float)* – Metrics for the shape, depends on `type`.  
- `type` *(str)* – Shape type. Supported values:  
  - `"quadrate"` – requires **1 argument**: side  
  - `"rectangle"` – requires **2 arguments**: width, height  
  - `"triangle_h"` – requires **2 arguments**: base, height  
  - `"triangle_s"` – requires **3 arguments**: side a, side b, side c (Heron’s formula)  
  - `"circle"` – requires **1 argument**: radius  
  - `"trapezoid"` – requires **3 arguments**: base a, base b, height  
  - `"rhombus"` – requires **2 arguments**: diagonal d1, diagonal d2  
  - `"parallelogram"` – requires **2 arguments**: base, height  
  - `"sector"` – requires **2 arguments**: angle (deg), radius  
  - `"ellipse"` – requires **2 arguments**: half-axis a, half-axis b  
  - `"polygon"` – requires **3 arguments**: n (sides), inscribed circle radius, side length  
  - `"sphere"` – requires **1 argument**: radius (returns surface area)  

**Returns**:  
- *(float)* – area of the specified shape  

**Raises**:  
- `TypeError` – if inputs are not numbers or `type` is not a string  
- `ValueError` – if shape type is invalid, wrong number of arguments, or non-positive metrics  

**Examples**:  
```python
square(5, type="quadrate")        # → 25  
square(3, 4, type="rectangle")    # → 12  
square(6, 8, type="triangle_h")   # → 24  
square(3, type="circle")          # → 28.26  
square(5, 7, 9, type="triangle_s")# → 15.59 (Heron’s formula)  
square(10, type="sphere")         # → 1256.0  
```

### Area-calculation
- The square function calculates the area of various 2D shapes based on the specified shape type and corresponding metrics. This function is designed to handle multiple geometric shapes and includes robust input validation for accurate area calculations.

**Parameters**
```python
*args (float):
```
 A variable-length argument list that represents the necessary metrics for the specified shape (e.g., side lengths, radius). The number of arguments required varies depending on the shape type.

```python
type (str):
```
 A string that specifies the type of shape for which the area is to be calculated. Supported types include:

'quadrate'
'rectangle'
'triangle_h' (triangle with base and height)
'triangle_s' (triangle with three sides)
'circle'
'trapezoid'
'rhombus'
'parallelogram'
'sector'
'ellipse'
'polygon'
'sphere' (note: typically, spheres are 3D; area may refer to the surface area calculation)
Returns
float: The function returns the calculated area of the specified shape.
Raises
TypeError:

If any of the input metrics (*args) are not numeric (i.e., not of type int or float).
If the type parameter is not a string.
ValueError:

If the specified shape type is invalid (not one of the recognized types).
If the number of provided arguments does not match the expected count for the specified shape type.
If any of the provided metrics are non-positive (i.e., less than or equal to zero).

**Example of usage**

> Calculate the area of a square with side length 4
area_square = square(4, type='quadrate')  # Expected output: 16.0

> Calculate the area of a rectangle with width 3 and height 5
area_rectangle = square(3, 5, type='rectangle')  # Expected output: 15.0

> Calculate the area of a triangle with base 4 and height 3
area_triangle_h = square(4, 3, type='triangle_h')  # Expected output: 6.0

> Calculate the area of a circle with radius 2
area_circle = square(2, type='circle')  # Expected output: 12.56

> Invalid usage example
area_invalid = square(3, type='invalid_shape')  
This will raise ValueError

### Distance-calculation
 -**Function: distance**
Calculates various types of distances based on the specified type and dimension.

**Parameters**
```python
*args (float):
```
Coordinates or parameters required for distance calculation.
```python
type (str):
```
 The type of distance to calculate. Supported types include:
'dist_points'
'dist_point_line'
'dist_point_plane'
'dist_par_lines'
'dist_par_planes'
'dist_vectors'
'dist_manhattan'
'dist_cos'
'dist_Chebyshev'
dimension (str): The dimension of the space in which to calculate the distance. Acceptable values are:
'2d'
'3d'
'euclid'
Returns
float: The calculated distance based on the specified type and dimension.
Raises
TypeError: If any of the arguments are not numeric, or if type or dimension are not strings.
ValueError: If the type or dimension is invalid.

**Example of usage**

> Calculate distance between two points in 2D
dist = distance(0, 0, 3, 4, type='dist_points', dimension='2d')  # Output: 5.0

> Calculate Manhattan distance in 3D
manhattan_dist = distance(1, 2, 3, 4, 5, 6, type='dist_manhattan', dimension='3d')  # Output: 9.0

**Function: circumference**
Calculates the circumference of a circle.

Parameters
```python
r (float):
```
The radius of the circle.
Returns
float: The calculated circumference of the circle.
Raises
TypeError: If the radius is not a number.

**Example of usage**

> Calculate the circumference of a circle with radius 5
circ = circumference(5)  # Output: 31.400000000000002


Here's an explanation for the distance, circumference, **arc_length**, and **vector_length** functions from your Mathhunt library. This documentation will help users understand the purpose, parameters, return values, and potential exceptions raised by each function.

 -**Function: arc_length**
Calculates the length of an arc of a circle.

Parameters
```python
r (float):
```
 The radius of the circle.
```python
rad (float):
```
 The angle in radians.
Returns
float: The calculated arc length.
Raises
TypeError: If either r or rad is not a number.
ValueError: If the angle is out of the valid range.

**Example of usage**

> Calculate the length of an arc with radius 10 and angle π/2
```python
arc = arc_length(10, 1.5708)  # Output: 15.707999999999998
```

 -**Function: vector_length**
Calculates the length of a vector.

*Parameters*
```python
*args (float):
```
 The components of the vector.
```python
dimension (str):
```
 The dimension of the vector, either '2d' or '3d'.
**Returns**
float: The calculated length of the vector.
**Raises**
TypeError: If any arguments are not valid numbers or if dimension is not a string.
ValueError: If dimension is invalid.

**Example of usage**

> Calculate the length of a 2D vector (3, 4)
```python
vec_length_2d = vector_length(3, 4, dimension='2d')  # Output: 5.0
```
```python
vec_length_2d = vector_length(3, 4, dimension='2d')  # Output: 5.0
```

> Calculate the length of a 3D vector (1, 2, 2)
```python
vec_length_3d = vector_length(1, 2, 2, dimension='3d')  # Output: 3.0
```

## Mathematical Functions

### `linear_function(a: float, x: float, b: float) -> float`  
Calculates the value of a linear function **ax + b**.  

**Arguments**:  
- `a` *(float)* – coefficient of x  
- `x` *(float)* – input variable  
- `b` *(float)* – constant term  

**Returns**:  
- *(float)* – result of `ax + b`  

---

### `quadratic_function(a: float, x: float, b: float, c: float) -> float`  
Calculates the value of a quadratic function **ax² + bx + c**.  

**Arguments**:  
- `a` *(float)* – coefficient of x²  
- `x` *(float)* – input variable  
- `b` *(float)* – coefficient of x  
- `c` *(float)* – constant term  

**Raises**:  
- `ValueError` if `a = 0`  

**Returns**:  
- *(float)* – result of `ax² + bx + c`  

---

### Power and Root Functions

### `power_function(x: float, n: float) -> float`  
Raises a number `x` to the power of `n`.  

**Arguments**:  
- `x` *(float)* – base  
- `n` *(float)* – exponent  

**Returns**:  
- *(float)* – result of `xⁿ`  

---

### `root_function(x: float, n: float) -> float`  
Calculates the **n-th root** of a number `x`.  

**Arguments**:  
- `x` *(float)* – number to extract the root from  
- `n` *(float)* – degree of the root  

**Raises**:  
- `ValueError` if `x < 0`  

**Returns**:  
- *(float)* – result of `x^(1/n)`  

---

### `pointer_function(x: float, a: float) -> float`  
Calculates **a raised to the power of x**.  

**Arguments**:  
- `x` *(float)* – exponent  
- `a` *(float)* – base  

**Returns**:  
- *(float)* – result of `a^x`  

---

### `logarithm_function(a: float, x: float) -> float`  
Calculates the logarithm of `x` with base `a`.  

**Arguments**:  
- `a` *(float)* – base of the logarithm (must be > 0 and != 1)  
- `x` *(float)* – argument of the logarithm (must be > 0)  

**Returns**:  
- *(float)* – logₐ(x)  

---

### Absolute Value

### `absolut_function(x: float) -> float`  
Returns the absolute value of a number.  

**Arguments**:  
- `x` *(float)* – input number  

**Returns**:  
- *(float)* – |x|  

---

### Trigonometric Functions (Bradis Table)

### `sinus(x: float, type: str) -> float`  
Calculates the sine of an angle.  

**Arguments**:  
- `x` *(float)* – angle  
- `type` *(str)* – `"deg"` for degrees, `"rad"` for radians  

**Returns**:  
- *(float)* – sin(x)  

---

### `cosinus(x: float, type: str) -> float`  
Calculates the cosine of an angle.  

**Arguments**:  
- `x` *(float)* – angle  
- `type` *(str)* – `"deg"` or `"rad"`  

**Returns**:  
- *(float)* – cos(x)  

---

### `tangens(x: float, type: str) -> float`  
Calculates the tangent of an angle.  

**Arguments**:  
- `x` *(float)* – angle  
- `type` *(str)* – `"deg"` or `"rad"`  

**Returns**:  
- *(float)* – tan(x)  

---

### `cotangens(x: float, type: str) -> float`  
Calculates the cotangent of an angle.  

**Arguments**:  
- `x` *(float)* – angle  
- `type` *(str)* – `"deg"` or `"rad"`  

**Returns**:  
- *(float)* – cot(x)  

---

### Inverse Trigonometric Functions

### `arcsin(x: float) -> float`  
Finds the arcsine of `x` using Bradis table.  

**Arguments**:  
- `x` *(float)* – sine value  

**Returns**:  
- *(float)* – angle in degrees  

---

### `arccos(x: float) -> float`  
Finds the arccosine of `x`.  

**Arguments**:  
- `x` *(float)* – cosine value  

**Returns**:  
- *(float)* – angle in degrees  

---

### `arctan(x: float) -> float`  
Finds the arctangent of `x`.  

**Arguments**:  
- `x` *(float)* – tangent value  

**Returns**:  
- *(float)* – angle in degrees  

---

### `arccot(x: float) -> float`  
Finds the arccotangent of `x`.  

**Arguments**:  
- `x` *(float)* – cotangent value  

**Returns**:  
- *(float)* – angle in degrees  

---

### Exponential and Hyperbolic Functions

### `exponential_function(x: float) -> float`  
Calculates **e^x**.  

**Arguments**:  
- `x` *(float)* – exponent  

**Returns**:  
- *(float)* – e^x  

---

### `sinh(x: float) -> float`  
Calculates the hyperbolic sine of `x`.  

**Arguments**:  
- `x` *(float)* – input value  

**Returns**:  
- *(float)* – sinh(x)  

---

### `cosh(x: float) -> float`  
Calculates the hyperbolic cosine of `x`.  

**Arguments**:  
- `x` *(float)* – input value  

**Returns**:  
- *(float)* – cosh(x)  

---

### `tanh(x: float) -> float`  
Calculates the hyperbolic tangent of `x`.  

**Arguments**:  
- `x` *(float)* – input value  

**Returns**:  
- *(float)* – tanh(x)  

---

### `coth(x: float) -> float`  
Calculates the hyperbolic cotangent of `x`.  

**Arguments**:  
- `x` *(float)* – input value  

**Returns**:  
- *(float)* – coth(x)  

---

### Summation and Product

### `sigma(i: int, n: int, equation: float = 0.0) -> float`  
Calculates the sum of integers from `i` to `n`.  

**Arguments**:  
- `i` *(int)* – start index  
- `n` *(int)* – end index  
- `equation` *(float, optional)* – initial value (default `0.0`)  

**Returns**:  
- *(float)* – total sum  

---

### `sigma_p(i: int, n: int, equation: float = 1.0) -> float`  
Calculates the product of integers from `i` to `n`.  

**Arguments**:  
- `i` *(int)* – start index  
- `n` *(int)* – end index  
- `equation` *(float, optional)* – initial value (default `1.0`)  

**Returns**:  
- *(float)* – total product  

## Visualization

In that module you can implement models of 2D figures in the graphical representation.

**Example of usage**

> Draw a rectangle with A=4 and B=2
```python
from mathhunt.viz.functions import *

create_rectangle(4, 2, dimension="2d")

show()
```

![alt text](image.png)

As you saw here was used function `show()` in the end of the code. That is a powerfull instrument that gives us an opportunity to draw several figures in a one plot simultaneuosly.

**Example of usage**

> Draw a rectangle with A=22 and B=12
> Draw a circle with r=10
```python
from mathhunt.viz.functions import *

create_rectangle(4, 2, dimension="2d")
create_circle(10, dimension="2d")

show()
```
![alt text](image-1.png)

But you should be careful in usage because all figures are implemented in a queue-tendency. For example that code will cause some trouble because the circle is bigger than square and it gives no space for quadrate to be visible.


```python
from mathhunt.viz.functions import *

create_quadrate(2, dimension="2d")
create_circle(10, dimension="2d")

show()
```

![alt text](image-2.png)

### `create_quadrate(*args: float, dimension: str)`
- Draws a 2D quadrate (square) centered at the origin.

**Arguments**:  
- `a` *(float)* – input side  
- `dimension` *(str)* – 2d (only)

### `create_reactangle(*args: float, dimension: str)`
- Draws a 2D rectangle centered at the origin.

**Arguments**:  
- `a` *(float)* – input side A
- `b` *(float)* – input side B 
- `dimension` *(str)* – 2d (only)

### `create_circle(*args: float, dimension: str)`
- Draws a 2D circle centered at the origin.

**Arguments**:  
- `r` *(float)* – input radius
- `dimension` *(str)* – 2d (only)

### `create_triangle(*args: float, dimension: str)`
- Draws a 2D trianle centered at the origin.

**Arguments**:  
- `a` *(float)* – input length A
- `b` *(float)* – input length B
- `c` *(float)* – input length C
- `dimension` *(str)* – 2d (only)

### `create_trapezoid(*args: float, dimension: str)`
- Draws a 2D trapezoid centered at the origin.

**Arguments**:  
- `ad` *(float)* – input length AD
- `bc` *(float)* – input length BC
- `ab` *(float)* – input length AB
- `cd` *(float)* – input length CD

- `dimension` *(str)* – 2d (only)

### `animate_monte_carlo(n_points: int)`
- Animate Monte-Carlo method with auto acceleration.

**Arguments**:  
- `n_points` *(int)* – Amount of points

That function is animated. So we should use a little bit simplier syntax to run the simulation. All funjctions with animations will be used as follows:

**Example of usage**

> Run the animation with 1000 points.
```python
from mathhunt.viz.animations import *

animate_monte_carlo(1000)

```

As you have seen here you should not use `show()` function in the end of a script. That makes animation logic easy to use.

![alt text](image-3.png)

## Probability

In that module you can use some functions to calculate probability.

**Example of usage**

> Find all the possible formations for 11 players on a football field
```python
from mathhunt.probability.functions import P_n

print(P_n(11.0))

```

### `fact(n: float, type: str) -> float`
- Calculate the factorial of a non-negative integer n.

**Arguments**:  
- `n` *(int)* – A non-negative integer.

### `P_n(n: float) -> int`
- Calculate the number of permutations of n elements.

**Arguments**:  
- `n` *(float)* – A non-negative float.

### `A_n_k(n: float, k: float) -> int`
- Calculate the number of arrangements of n elements taken k at a time.

**Arguments**:  
- `n` *(float)* – A non-negative float.
- `k` *(float)* – A non-negative float less than or equal to n.

### `C_n_k(n: float, k: float) -> int`
- Calculate the number of combinations of n elements taken k at a time.

**Arguments**:  
- `n` *(float)* – A non-negative float.
- `k` *(float)* – A non-negative float less than or equal to n.

### `P(event_outcomes: float, total_outcomes: float) -> float`
- Calculate the probability of an event.

**Arguments**:  
- `event_outcomes` *(float)* – Number of favorable outcomes for the event.
- `total_outcomes` *(float)* – Total number of possible outcomes.

### `roll(sides: int = 6) -> int`
- Simulate rolling a die with a given number of sides.

**Arguments**:  
- `sides` *(int)* – Number of sides on the die (default is 6).

**Returns**:
- An integer representing the result of the die roll.

### `flip() -> str`
-  Simulate flipping a coin.

**Returns**:
- A string representing the result of the coin flip ("Heads" or "Tails").

### `generate_monte_carlo_point()`
-  Generates a random point in [-1, 1]x[-1, 1] and checks if it's inside unit circle.

**Returns**:
- (x, y, is_inside)

## Logic

In that module you can use features of boolean algebra.

> Soon.