### Install forallpeople Python Package

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/index.ipynb

Installs the forallpeople Python library using pip. This is the first step to using the library for unit-aware calculations.

```bash
pip install forallpeople
```

--------------------------------

### Auto-prefixing with SI Units in Python

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Demonstrates how forallpeople automatically applies SI prefixes to units for conventional representation. It shows examples of current, resistance, and voltage, highlighting when prefixes are applied and why.

```python
>>> current = 0.5 * A
>>> current
500.000 mA # 'current' is auto-prefixed to 500 milliamperes
>>> resistance = 1200 * Ohm
>>> resistance
1.200 kΩ # 'resistance' is auto-prefixed to kilo-ohms
>>> voltage = current * resistance
>>> voltage
600.000 V # 'voltage' does not have a prefix because its value is above 1 V but less than 1000 V
```

--------------------------------

### Defining Custom Unit Environments in JSON

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Provides an example of how to define custom unit environments using a JSON format. It shows the structure required for 'Dimension', 'Value', 'Factor', and 'Symbol', with specific examples for kilopascals and pounds-force.

```json
{
    "Name": {
        "Dimension": [0,0,0,0,0,0,0],
        "Value": 1,
        "Factor": 1,
        "Symbol": ""
    }
}

"kPa": {
    "Dimension": [1,-1,-2,0,0,0,0],
    "Value": 1000
},
"lb-f": {
    "Dimension": [1, 1, -2, 0, 0, 0, 0],
    "Factor": "1/0.45359237/9.80665",
    "Symbol": "lb"
}
```

--------------------------------

### Using Physicals with NumPy Matrix Operations in Python

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Demonstrates the integration of forallpeople's 'Physical' objects with NumPy for matrix operations. It shows examples of matrix addition, multiplication, subtraction, and division using instances of 'Physical'.

```python
>>> import numpy as np
>>> a = 5 * si.kN
>>> b = 3.5 * si.kN
>>> c = 7.7 * si.kN
>>> d = 6.6 * si.kN
>>> m1 = np.matrix([[a, b], [b, a]])
>>> m2 = np.matrix([[c, d], [d, c]])
>>> m1
matrix([
[5.000 kN, 3.500 kN],
[3.500 kN, 5.000 kN]], dtype=object)
>>> m2
matrix([
[7.700 kN, 6.600 kN],
[6.600 kN, 7.700 kN]], dtype=object)
>>> m1 + m2
matrix([
[12.700 kN, 10.100 kN],
[10.100 kN, 12.700 kN]], dtype=object)
>>> m1 @ m2
matrix([
[61.600 kN², 59.950 kN²],
[59.950 kN², 61.600 kN²]], dtype=object)
>>> m2 - m1
matrix([
[2.700 kN, 3.100 kN],
[3.100 kN, 2.700 kN]], dtype=object)
>>> m1 / m2
matrix([
[0.6493506493506493, 0.5303030303030303],
[0.5303030303030303, 0.6493506493506493]], dtype=object)
```

--------------------------------

### US Customary Environment Units (Python)

Source: https://context7.com/connorferster/forallpeople/llms.txt

Illustrates the 'us_customary' environment in forallpeople, focusing on US measurement units for general calculations. Includes examples of length, mass, force, and volume conversions, noting limitations with temperature.

```python
import forallpeople as si
si.environment('us_customary')

# Length units
distance = 5280 * si.ft
miles = distance.to('mile')
print(miles)  # Output: 1.000 mile

# Weight/Mass
mass = 10 * si.lbm
print(mass)  # Output: 10.000 lbm

# Force
force = 1000 * si.lbf
kips = force.to('kip')
print(kips)  # Output: 1.000 kip

# Volume
volume = 32 * si.fl_ounce
quarts = volume.to('quart')
print(quarts)  # Output: 1.000 qt.

# Temperature (factor-based conversion)
temp = 100 * si.K
# Note: Temperature requires offset conversion not handled by factors
```

--------------------------------

### Perform calculation with SI units (module namespace)

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

This Python example demonstrates a basic calculation using forallpeople. It defines area and force using SI units (meters and newtons) and then calculates pressure, which is automatically represented in Pascals.

```python
area = 3*si.m * 4*si.m
force = 2500 * si.N
print(force / area)
```

--------------------------------

### Unit Cancellation to Float in Forallpeople

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/standard_behaviours.ipynb

Shows how unit cancellation occurs in forallpeople when physical quantities are multiplied or divided, resulting in a dimensionless float. Examples include calculating the number of spaces and cycles.

```python
import forallpeople as si
length = 4.2 * si.m
spacing = 0.25 * si.m
num_of_spaces = length / spacing
display(num_of_spaces)
a = 40 * si.Hz
b = 3 * si.s
cycles = a * b
display(cycles)
```

--------------------------------

### Get Formatted String Representations: latex and html (Python)

Source: https://context7.com/connorferster/forallpeople/llms.txt

Generates formatted string representations of physical quantities for use in documents, web pages, and Jupyter notebooks. Supports LaTeX for mathematical typesetting and HTML for rich text display. Also demonstrates string formatting with format codes for controlling precision and unit prefixes.

```python
import forallpeople as si
si.environment('default')

# Create physical quantities
force = 2.5 * si.N * 1000
area = 0.01 * si.m**2
stress = force / area

# LaTeX representation (for documents)
print(stress.latex)
# Output: $250.000\ \mathrm{kPa}$

# HTML representation (for web/Jupyter)
print(stress.html)
# Output: 250.000 kPa

# Power with exponents
velocity = 5 * si.m / si.s
kinetic_factor = velocity**2
print(kinetic_factor.latex)
# Output: $25.000\ \mathrm{m}^{2}·\mathrm{s}^{-2}$

# String formatting with format codes
energy = 1234.5678 * si.J
print(f"{energy:.2f}")     # Output: 1.23 kJ
print(f"{energy:.4e}")     # Output: 1.2346e+03 J
print(f"{energy:.2fL}")    # Output: $1.23\ \mathrm{kJ}$ (LaTeX)
print(f"{energy:.2fH}")    # Output: 1.23 kJ (HTML)
```

--------------------------------

### Manual Unit Application for Square Root Calculation (Strategy 3)

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/empiricals.ipynb

Illustrates a strategy where the numerical value is extracted before the square root operation, and the unit is applied afterward. This is useful when a formula intends to compute the square root of a numerical value and then apply specific units to the result, as shown in the example with `f_c`.

```python
import math
MPa = 1e6 * si.Pa
f_c = 35 * MPa

value, unit = f_c.split()
math.sqrt(value) * unit
```

--------------------------------

### Calculate Force in SI Base Units (Python)

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/background.ipynb

Demonstrates calculating a force using SI base units (meters, seconds, kilograms) and printing the result in its default representation (kg·m·s⁻²). This example initializes constants for gravity and mass and then computes the force.

```python
import forallpeople as si

G = 9.81 * (si.m/si.s**2)
m = 3200.5*si.kg
force = m*G
print(force) # 318.825 kg·m·s⁻²
```

--------------------------------

### Create and Use Physical Quantities in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Illustrates how to create physical quantities by multiplying unit variables with numerical values and performing calculations. Demonstrates basic arithmetic operations with units.

```python
mass = 5.25 * si.kg
g = 9.81 * si.m/si.s**2
print(mass*g)
```

--------------------------------

### Format Physical Quantities with Standard Python String Formatting

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Demonstrates how to format `Physical` instances using standard Python string formatting codes like precision and scientific notation. This allows control over the output representation of physical quantities.

```python
mass = 32.902392 * kg
g = 9.8065 * m/s**2
force = mass * g
force # Default format is {:.3f}

print("{:.6f}".format(force))
print("{:.4e}".format(force))
```

--------------------------------

### Physical Instance Components and Immutability

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Demonstrates the structure of a `Physical` instance, including its value, dimensions, factor, precision, and prefix. It also highlights the immutability of `Physical` instances, preventing direct attribute setting and emphasizing that operations return new instances.

```python
from forallpeople import si

# Example of creating a Physical instance (e.g., 5 meters)
length = 5 * si.m

# Accessing components (read-only)
print(f"Value: {length.value}")
print(f"Dimensions: {length.dimensions}")
print(f"Factor: {length.factor}")
print(f"Precision: {length.precision}")
print(f"Prefixed: {length.prefixed}")

# Attempting to set attributes directly will raise an error (due to immutability)
# try:
#     length.value = 10
# except AttributeError as e:
#     print(f"Error: {e}")

# Arithmetic operations return new instances
new_length = length + (2 * si.m)
print(f"New length: {new_length}")
```

--------------------------------

### Load and Apply a Custom Units Environment in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Explains how to load a specific units environment (e.g., 'default.json') using `si.environment()`. This modifies the unit representations and adds new unit variables to the namespace.

```python
si.environment('default') # Load the default.json environment
print(mass*g)
```

--------------------------------

### Import and Load Environment (Python)

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/interface.ipynb

Imports the forallpeople library and loads the default environment. This sets up the namespace with predefined unit instances.

```python
import forallpeople as si
si.environment('default')
```

--------------------------------

### Arithmetic Operations on Physical Instances (Python)

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Demonstrates various arithmetic operations on `Physical` instances, including addition, subtraction, multiplication, and division. It covers scenarios involving instances with numbers and instances with matching or differing dimensions.

```python
from forallpeople import si

# Addition and Subtraction
length_m = 5 * si.m
other_length_m = 2 * si.m
number = 10

sum_lengths = length_m + other_length_m
print(f"Sum of lengths: {sum_lengths}") # Expected: 7.0 m

subtracted_value = length_m - number
print(f"Length minus number: {subtracted_value}") # Expected: -5.0 m

# Multiplication
velocity_mps = 3 * si.m / si.s
acceleration_mps2 = 2 * si.m / (si.s ** 2)
scalar = 4.5

product_vel_scalar = velocity_mps * scalar
print(f"Velocity * scalar: {product_vel_scalar}") # Expected: 13.5 m/s

product_lengths_mass = length_m * (3 * si.kg)
print(f"Length * mass: {product_lengths_mass}") # Expected: 15.0 m kg

# True Division
division_lengths = length_m / other_length_m
print(f"Length / Length: {division_lengths}") # Expected: 2.5 (dimensionless float)

division_vel_scalar = velocity_mps / scalar
print(f"Velocity / scalar: {division_vel_scalar}") # Expected: 0.666... m/s

# Power
length_cubed = si.m ** 3
print(f"Meters cubed: {length_cubed}") # Expected: 1.0 m^3

# Absolute Value and Negation
negative_length = -5 * si.m
abs_length = abs(negative_length)
print(f"Absolute length: {abs_length}") # Expected: 5.0 m
negated_length = -length_m
print(f"Negated length: {negated_length}") # Expected: -5.0 m
```

--------------------------------

### Loading SI Environments and Using Derived Units in Python

Source: https://context7.com/connorferster/forallpeople/llms.txt

Explains how to load a units environment in forallpeople to access derived SI units and customize quantity display. The 'default' environment includes common derived units like Newtons, Pascals, and Joules.

```python
import forallpeople as si

# Load the default environment
si.environment('default')

# Now derived units are available
force = 500 * si.N
area = 0.25 * si.m**2
pressure = force / area
print(pressure)  # Output: 2.000 kPa (auto-prefixed)

# Energy calculation
energy = 1500 * si.J
power = 300 * si.W
time_duration = energy / power
print(time_duration)  # Output: 5.000 s

# Electrical calculations
voltage = 12 * si.V
resistance = 1200 * si.Ohm
current = voltage / resistance
print(current)  # Output: 10.000 mA (auto-prefixed)

# See all available units in current environment
si.environment()  # Prints dict of all loaded units
```

--------------------------------

### Physical Quantity Properties and Methods

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Demonstrates the core properties and methods of the Physical class in forallpeople. This includes accessing the numerical value, dimensions, scaling factor, and string representations (latex, html, repr). It also shows how to use methods like round, sqrt, split, and to for manipulating physical quantities.

```python
import forallpeople as si

si.environment('default')

# Example usage of properties
MPa = 1e6 * si.Pa
f_c = 35 * MPa

print(f"Value: {f_c.value}")
print(f"Dimensions: {f_c.dimensions}")
print(f"Factor: {f_c.factor}")
print(f"Latex: {f_c.latex}")
print(f"HTML: {f_c.html}")
print(f"Repr: {f_c.repr}")

# Example usage of methods
rounded_f_c = f_c.round(2)
print(f"Rounded: {rounded_f_c}")

squared_root = f_c.sqrt()
print(f"Square root: {squared_root}")

value_part, dimension_part = f_c.split()
print(f"Split value: {value_part}")
print(f"Split dimension: {dimension_part}")

# Example of .to() method (assuming 'psi' is a defined unit)
# try:
#     psi_f_c = f_c.to('psi')
#     print(f"Converted to psi: {psi_f_c}")
# except ValueError as e:
#     print(e)

# If .to() is called without arguments, it prints available units
# f_c.to()

```

--------------------------------

### Structural Environment Units (Python)

Source: https://context7.com/connorferster/forallpeople/llms.txt

Demonstrates the usage of the 'structural' environment in forallpeople, which includes common metric and US customary units for structural engineering. Shows calculations with these units and conversion between different unit systems.

```python
import forallpeople as si
si.environment('structural')

# Metric structural units
force = 50 * si.kN
moment = 100 * si.Nm
stress = 25 * si.MPa

# US customary structural units
beam_length = 20 * si.ft
point_load = 5 * si.kip
pressure = 4 * si.ksi

# Mixed calculations
area = 100 * si.mm * 200 * si.mm
force_result = stress * area
print(force_result)  # Output in N or kN

# Convert between systems
force_si = 10 * si.kN
force_imperial = force_si.to('kip')
print(force_imperial)  # Output: 2.248 kip

# Moment in imperial
moment_lb = (1000 * si.Nm).to('lbft')
print(moment_lb)  # Output: 737.562 lb·ft
```

--------------------------------

### Basic SI Unit Access and Calculations in Python

Source: https://context7.com/connorferster/forallpeople/llms.txt

Demonstrates importing the forallpeople library and accessing SI base units for calculations. It shows how dimensions combine automatically during multiplication and division, and how division of same dimensions results in a float.

```python
import forallpeople as si

# Access base units directly from module
mass = 25 * si.kg
length = 10 * si.m
time = 5 * si.s

# Perform calculations - dimensions combine automatically
velocity = length / time
print(velocity)  # Output: 2.000 m·s⁻¹

# Acceleration
acceleration = velocity / time
print(acceleration)  # Output: 0.400 m·s⁻²

# Force (mass * acceleration)
force = mass * acceleration
print(force)  # Output: 10.000 kg·m·s⁻²

# Division of same dimensions returns a float
ratio = (10 * si.m) / (5 * si.m)
print(ratio)  # Output: 2.0 (float, not Physical)
```

--------------------------------

### Handling Dimensionally Inconsistent Calculations

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Illustrates how forallpeople manages calculations where dimensions might seem inconsistent, such as taking the square root of a pressure unit. It shows how the library's `__float__` implementation affects calculations and how to choose between operating on the displayed value or the base SI value.

```python
>>> import forallpeople as si
>>> from math import sqrt
>>> si.environment('default')
>>> MPa = 1e6 * si.Pa
>>> f_c = 35 * MPa
>>> # Calculation that appears dimensionally inconsistent
>>> sqrt(f_c) * MPa
5.916 MPa

>>> # Demonstrating the effect of float() conversion
>>> f_c # As expected
35.000 MPa
>>> float(f_c) # The numerical portion of the prefixed unit
35.0
>>> f_c.value # The actual value in base SI units (Pascals)
35000000.0
>>> sqrt(f_c) # Sqrt of the displayed value '35'
5.916079783099616
>>> sqrt(f_c.value) # Sqrt of the base SI value '35000000.0'
5916.079783099616

```

--------------------------------

### View Accessible Unit Variables in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Demonstrates how to inspect the current unit variables available in the forallpeople namespace after loading a specific environment. This helps in understanding which units are currently defined.

```python
# See the names of the new variables accessible in the namespace
si.environment()
```

--------------------------------

### Physical Class Methods

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

This section details the methods available for Physical instances. Most methods return a new, immutable Physical instance.

```APIDOC
## Physical Class Methods

Almost all methods return a new `Physical` instance because all instances are **immutable**.

### Methods

* `.round(self, n: int)`: Returns a `Physical` instance identical to `self` but with the display precision set to `n`. The built-in `round()` function can also be used.
* `.sqrt(self, n: float = None)`: Returns a `Physical` representing the square root of `self`. An optional `n` can be set to compute alternate roots.
* `.split(self)`: Returns a 2-tuple: the 0-th element is the `.value` and the 1-th element is a `Physical` instance with a value of 1 (representing only the dimensional part). This is useful for computations requiring only numerical input, like `numpy.linalg.inv()`.
* `.to(self, unit_name: str = "")`: Returns a new `Physical` instance with a `.factor` corresponding to a dimensionally compatible unit defined in the `environment`. If called without arguments, a list of available units for the quantity is printed to `stdout`.
```

--------------------------------

### Auto-scaling of Units in Forallpeople

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/standard_behaviours.ipynb

Illustrates the auto-scaling feature of the forallpeople library, where quantities are automatically represented using appropriate scaled units (e.g., kg to Mg, s to GHz, m to nm). It also shows cases where auto-scaling is not applied, such as for undefined products of base units or instances of defined units with non-unity factors.

```python
import forallpeople as si
si.environment('default')
display(5000 * si.kg) # Auto-scaling to Mg
display(4_000_000_000 / si.s) # Auto-scaling to GHz
display(0.000000112 * si.m) # Auto-scaling to nm
display(40000 * si.A * si.kg) # No auto-scaling because kg*A is not in the environment
si.environment('us_customary')
display(40000 * si.lbf)
```

--------------------------------

### Display Force in Newtons using Default Environment (Python)

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/background.ipynb

Shows how to load the 'default' SI environment to represent a previously calculated force in Newtons (N). The underlying physical quantity remains unchanged, but its representation is altered to use derived SI units.

```python
import forallpeople as si

G = 9.81 * (si.m/si.s**2)
m = 3200.5*si.kg
force = m*G
print(force) # 318.825 kg·m·s⁻²
si.environment('default')
print(force) # 318.825 N
```

--------------------------------

### Handling Dimensionally Inconsistent Calculations

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Demonstrates how the Forallpeople library handles calculations where dimensions might seem to disappear or change unexpectedly, such as in certain engineering codes.

```APIDOC
## Dimensionally Inconsistent Calculations

It is not uncommon for some calculations to use formulas whose dimensions seem to magically appear on their own. The `forallpeople` library can handle these calculations if the "hidden dimensions" are recognized and accounted for by the user.

Example: in the Canadian concrete design code it is recognized that `sqrt(1*MPa)` results in units of MPa instead of MPa<sup>0.5</sup>. Here is one way this can be managed in `forallpeople`:

```python
>>> import forallpeople as si
>>> from math import sqrt
>>> si.environment('default')
>>> MPa = 1e6 * si.Pa
>>> f_c = 35 * MPa
>>> sqrt(f_c) * MPa
5.916 MPa
```

This behavior occurs because of the way `__float__` is defined in the `Physical` class: if `float()` is called on a `Physical`, the returned value will be the numerical portion of the auto-reduced, auto-prefixed unit representation.

Example:

```python
>>> import forallpeople as si
>>> from math import sqrt
>>> si.environment('default')
>>> MPa = 1e6 * si.Pa
>>> f_c = 35 * MPa
>>> f_c # As expected
35.000 MPa
>>> float(f_c) # The numerical portion of the prefixed unit
35.0
>>> f_c.value # However, the actual value is 35e6 Pa
35000000.0
>>> sqrt(f_c) # Sqrt of "35"
5.916079783099616
>>> sqrt(f_c.value) # Sqrt of "35000000.0"
5916.079783099616
```

Many of Python's math functions will first attempt to call `float()` on an argument that is not already a float. `forallpeople` takes advantage of this by ensuring the float value returned is the same number you would see in the unit representation. If you prefer the operation be performed on the base unit value, then simply substitute the `.value` value as the function argument.
```

--------------------------------

### Conventional Arithmetic with Physical Quantities in Forallpeople

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/standard_behaviours.ipynb

Demonstrates conventional arithmetic operations (addition, subtraction, multiplication, division, exponentiation) between physical quantities using the forallpeople library. It highlights that addition/subtraction require same dimensions, while multiplication/division create new dimensions. Floor division and modulo are currently undefined.

```python
import forallpeople as si
a = 500 * si.kg
b = 23 * si.kg
c = 300 * si.kg
display(a + b - c)
d = 9.81 * si.m / si.s**2
display(d)
```

--------------------------------

### Basic SI Unit Calculation in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/index.ipynb

Demonstrates a basic calculation using SI units (meters, seconds, kilograms) with the forallpeople library. It sets the environment to default and calculates force.

```python
import forallpeople as si
si.environment('default')

g = 9.81 * si.m/si.s**2
m = 3500 * si.kg
force = m * g
force
```

--------------------------------

### Auto-prefixing with Powers of Units in Python

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Illustrates how forallpeople handles auto-prefixing when units are raised to a power. It shows that the prefix is also considered part of the power, affecting the final representation, especially with large numbers.

```python
>>> a = 5000 * si.m
>>> a
5.000 km
>>> a**2
25.000 km² # Remember that the 'kilo' prefix is also being squared
>>> b = 500000 * si.m 
>>> b
500.000 km
>>> b**2
250000.000 km² # Why isn't this being shown as 250 Mm²? Because it would take 1,000,000 km² to make a Mm². This is only 250,000 km².
```

--------------------------------

### Interactive Import of forallpeople Library in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Shows how to perform an interactive import of the forallpeople library, making units directly available in the top-level namespace without the 'si.' prefix. Caution is advised due to potential variable name clashes.

```python
import forallpeople
forallpeople.environment('default', top_level=True)
```

--------------------------------

### Import forallpeople Library in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Demonstrates the standard way to import the forallpeople library for use in Python modules. This import makes SI units available under the 'si' namespace.

```python
import forallpeople as si
```

--------------------------------

### Matrix Operations with Units (Python)

Source: https://context7.com/connorferster/forallpeople/llms.txt

Demonstrates matrix addition, multiplication, and division using the forallpeople library, showcasing how units are preserved, combined, or canceled during these operations. Assumes `m1` is a pre-defined matrix with units.

```python
import forallpeople as si
import numpy as np

c = 7.7 * si.N * 1000
d = 6.6 * si.N * 1000
m1 = np.matrix([[c, d], [d, c]])
m2 = np.matrix([[c, d], [d, c]])

# Matrix addition preserves units
result_add = m1 + m2
print(result_add)

# Matrix multiplication combines units
result_mul = m1 @ m2
print(result_mul)

# Division cancels units
result_div = m1 / m2
print(result_div)  # Returns pure float matrix
```

--------------------------------

### Perform Calculations with Top-Level Units in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Illustrates performing calculations using units that are directly available in the top-level namespace due to an interactive import. This simplifies syntax for interactive sessions.

```python
mass = 5.25*kg
g = 9.81 * m/s**2
mass*g
```

--------------------------------

### Physical.prefix() for Manual SI Prefix Control in Python

Source: https://context7.com/connorferster/forallpeople/llms.txt

Shows how to use the `Physical.prefix()` method in forallpeople to manually control SI prefixing for quantities, overriding automatic prefixing. It allows specifying a desired prefix or using 'unity' for the base unit.

```python
import forallpeople as si
si.environment('default')

# Auto-prefixed by default
current = 0.005 * si.A
print(current)  # Output: 5.000 mA

# Force specific prefix
current_micro = current.prefix('μ')
print(current_micro)  # Output: 5000.000 μA

# Force no prefix (unity)
current_base = current.prefix('unity')
print(current_base)  # Output: 0.005 A

# Works with any SI prefix
resistance = 1500 * si.Ohm
print(resistance)  # Output: 1.500 kΩ

resistance_mega = (1500000 * si.Ohm).prefix('M')
print(resistance_mega)  # Output: 1.500 MΩ

resistance_base = resistance.prefix('unity')
print(resistance_base)  # Output: 1500.000 Ω
```

--------------------------------

### Physical Class Properties

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

This section details the properties available for each Physical instance, representing a physical quantity.

```APIDOC
## Physical Class Properties

Each `Physical` instance offers the following properties:

### Properties

* `.value`: A `float` that represents the numerical value of the physical quantity in SI base units.
* `.dimensions`: A `Dimensions` object (a `NamedTuple`) that describes the dimension of the quantity as a vector.
* `.factor`: A `float` that represents a factor for scaling the quantity into alternate unit systems (e.g., US customary units).
* `.latex`: A `str` representing the pretty-printed quantity in LaTeX code.
* `.html`: A `str` representing the pretty-printed quantity in HTML code.
* `.repr`: A `str` representing the traditional machine-readable `repr()` of the quantity. Defaults to a pretty-printed `__repr__()` for better compatibility.
```

--------------------------------

### Three-Decimal Precision and Rounding in Forallpeople

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/standard_behaviours.ipynb

Explains the default three-decimal precision for displayed physical quantities in forallpeople and how it can be modified. It demonstrates instance-level rounding using `round()` and module-level precision setting via environments. It also addresses potential display discrepancies when auto-scaling is not applicable.

```python
import forallpeople as si
si.environment('default')
a = 4230.2349329 * si.kg
display(a)
b = round(a, 6)
display(b)
c = 1 / (4000000 * si.kg * si.A)
display(c) # 0.000???
display(round(c, 9))
display("{:.3e}".format(c))
```

--------------------------------

### Display SI Base Units Environment in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Shows how to display the default SI base units available in the forallpeople environment. These units are instantiated as variables upon module import.

```python
si.environment()
```

--------------------------------

### Arithmetic Operations with Units (Python)

Source: https://context7.com/connorferster/forallpeople/llms.txt

Illustrates various arithmetic operations (addition, subtraction, multiplication, division, exponentiation, absolute value, negation) on physical instances using the forallpeople library. It highlights how dimensions are combined or subtracted and how units are handled.

```python
import forallpeople as si
si.environment('default')

# Addition/Subtraction (requires same dimensions)
length1 = 5 * si.m
length2 = 3 * si.m
total = length1 + length2
print(total)  # Output: 8.000 m

difference = length1 - length2
print(difference)  # Output: 2.000 m

# Adding number to Physical (assumes same unit)
extended = length1 + 2  # Adds 2 meters
print(extended)  # Output: 7.000 m

# Multiplication combines dimensions
force = 100 * si.N
distance = 5 * si.m
work = force * distance
print(work)  # Output: 500.000 J

# Division subtracts dimensions
power = 1000 * si.W
time = 10 * si.s
energy = power * time
print(energy)  # Output: 10.000 kJ

# Exponentiation
side = 4 * si.m
area = side ** 2
print(area)  # Output: 16.000 m²

volume = side ** 3
print(volume)  # Output: 64.000 m³

# Absolute value and negation
negative_temp = -5 * si.K
print(abs(negative_temp))  # Output: 5.000 °C
print(-negative_temp)      # Output: 5.000 °C
```

--------------------------------

### Top-Level Namespace Import for SI Units in Python

Source: https://context7.com/connorferster/forallpeople/llms.txt

Illustrates how to use `top_level=True` with forallpeople to import units directly into the global namespace, avoiding the `si.` prefix. This is particularly useful for interactive sessions and Jupyter notebooks.

```python
import forallpeople
forallpeople.environment('default', top_level=True)

# Units now available without prefix
mass = 75 * kg
gravity = 9.81 * m/s**2
weight = mass * gravity
print(weight)  # Output: 735.750 N

# Direct calculations
force = 2500 * N
area = 3 * m * 4 * m
stress = force / area
print(stress)  # Output: 208.333 Pa

# Power calculation
work = 5000 * J
time = 10 * s
power_output = work / time
print(power_output)  # Output: 500.000 W
```

--------------------------------

### Physical.to() for Unit Conversion in Python

Source: https://context7.com/connorferster/forallpeople/llms.txt

Demonstrates the `Physical.to()` method in forallpeople for converting physical quantities to compatible units defined in the loaded environment. Calling `.to()` without arguments lists available conversion options.

```python
import forallpeople as si
si.environment('structural')

# Create a force value
force = 4448.22 * si.N

# See available conversions for this dimension
force.to()  # Prints: lb, kip, etc.

# Convert to pounds-force
force_lb = force.to('lb')
print(force_lb)  # Output: 1000.000 lb

# Pressure conversions
pressure = 6894757 * si.Pa
pressure_psi = pressure.to('psi')
print(pressure_psi)  # Output: 1000.000 psi

pressure_ksi = pressure.to('ksi')
print(pressure_ksi)  # Output: 1.000 ksi

# Length conversions
length = 3.048 * si.m
length_ft = length.to('ft')
print(length_ft)  # Output: 10.000 ft
```

--------------------------------

### Load default environment in forallpeople (top-level namespace)

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

This Python command loads the default SI derived units environment. Setting top_level=True pushes the units directly into the top-level namespace, allowing you to use them without the 'si.' prefix (e.g., 'N' instead of 'si.N').

```python
si.environment('default', [top_level=True])
```

--------------------------------

### Power and Absolute/Negation Operations (Python)

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Details the power, absolute value, and negation operations for `Physical` instances. It clarifies that instances can be raised to a numeric power but not to another instance's power, and that absolute value and negation return new `Physical` instances.

```python
from forallpeople import si

# Power operation
volume = si.m ** 3
print(f"Volume (m^3): {volume}")

# Attempting to raise a Physical instance to another instance's power is not supported
# try:
#     result = si.m ** si.s
# except TypeError as e:
#     print(f"Error: {e}")

# Absolute value
negative_force = -10 * si.N
positive_force = abs(negative_force)
print(f"Absolute force: {positive_force}") # Expected: 10.0 N

# Negation
original_velocity = 5 * si.m / si.s
negated_velocity = -original_velocity
print(f"Negated velocity: {negated_velocity}") # Expected: -5.0 m/s
```

--------------------------------

### Load default environment in forallpeople (module namespace)

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

This Python command loads the default SI derived units environment. By setting top_level=False, the units are loaded into the 'si' module's namespace, requiring you to access them via 'si.unit_name'.

```python
si.environment('default', [top_level=False])
```

--------------------------------

### Dimension Vectors with tuplevector

Source: https://github.com/connorferster/forallpeople/blob/main/README.md

Illustrates how `Physical` instances use `Dimensions` objects, which are `NamedTuple`s, to track physical quantities. It shows how vector arithmetic from the `tuplevector` library is applied directly to these `Dimensions` objects.

```python
from forallpeople import si
from collections import namedtuple

# Assuming Dimensions is a namedtuple as described
# In a real scenario, this would be part of the forallpeople library
Dimensions = namedtuple('Dimensions', ['m', 'kg', 's', 'A', 'K', 'mol', 'cd'])

# Example dimensions for meters and seconds
dims_m = Dimensions(m=1, kg=0, s=0, A=0, K=0, mol=0, cd=0)
dims_s = Dimensions(m=0, kg=0, s=1, A=0, K=0, mol=0, cd=0)

# Vector addition of dimensions (e.g., for multiplication of quantities)
# This would typically be handled internally by the Physical class
# For demonstration, let's assume a simple vector addition function
def add_dimensions(d1, d2):
    return Dimensions(*[getattr(d1, f) + getattr(d2, f) for f in d1._fields])

# Example: Dimensions for meters * seconds
dims_m_times_s = add_dimensions(dims_m, dims_s)
print(f"Dimensions for m*s: {dims_m_times_s}")

# Example: Dimensions for meters / seconds
def subtract_dimensions(d1, d2):
    return Dimensions(*[getattr(d1, f) - getattr(d2, f) for f in d1._fields])

dims_m_per_s = subtract_dimensions(dims_m, dims_s)
print(f"Dimensions for m/s: {dims_m_per_s}")
```

--------------------------------

### Format Physical Quantities for HTML Output in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Shows how to format `Physical` instances for HTML output using the special format code 'H'. This generates strings suitable for rendering in web contexts, including special characters and superscripts.

```python
mass = 32.902392 * kg
g = 9.8065 * m/s**2
force = mass * g
print("{:.4eH}".format(force)) # Use 'H' to render HTML
```

--------------------------------

### Format Physical Quantities for LaTeX Output in Python

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/basic_usage.ipynb

Demonstrates how to format `Physical` instances for LaTeX output using the special format code 'L'. This generates strings compatible with LaTeX typesetting, including mathematical symbols and formatting.

```python
mass = 32.902392 * kg
g = 9.8065 * m/s**2
force = mass * g
print("{:.4eL}".format(force)) # Use 'L' to render LaTeX
```

--------------------------------

### Numerical Transformation for Wood Design Formula

Source: https://github.com/connorferster/forallpeople/blob/main/docs/source/empiricals.ipynb

Demonstrates how to handle empirical formulas that are strict numerical transformations by manually removing units from inputs and applying the expected output units (N) at the end. This involves converting input dimensions to floats and then scaling the final result.

```python
si.environment('default')
import math

# Use .prefix to force the numerical value to scale in mm
t = (0.354 * si.m).prefix('m')
d = (0.620 * si.m).prefix('m')
d_e = (0.480 * si.m).prefix('m')

t = float(t)
d = float(d)
d_e = float(d_e)

QS_i = 14 * t * math.sqrt(d_e / (1 - d_e/d)) * si.N
QS_i
```

--------------------------------

### Access Physical Properties: value, dimensions, factor, repr (Python)

Source: https://context7.com/connorferster/forallpeople/llms.txt

Provides access to the underlying components of a Physical instance, including its numerical value, dimensional representation, conversion factor, and a machine-readable string representation. These properties are essential for programmatic manipulation, debugging, and understanding the internal state of a physical quantity.

```python
import forallpeople as si
si.environment('default')

# Create a pressure value
pressure = 101325 * si.Pa

# Access raw SI base unit value
print(pressure.value)  # Output: 101325.0

# Access dimensions tuple (kg, m, s, A, cd, K, mol)
print(pressure.dimensions)  # Output: Dimensions(kg=1, m=-1, s=-2, A=0, cd=0, K=0, mol=0)

# Access the conversion factor (1 for SI units)
print(pressure.factor)  # Output: 1

# Machine-readable representation
print(pressure.repr)
# Output: Physical(value=101325.0, dimensions=Dimensions(kg=1, m=-1, s=-2, A=0, cd=0, K=0, mol=0), factor=1, precision=3, prefixed=)

# Conversion factor example with non-SI units
si.environment('structural')
force_lb = (100 * si.N).to('lb')
print(force_lb.factor)  # Output: Fraction(10000000000, 44482216152)
```

--------------------------------

### Define Custom Unit Environments (JSON and Python)

Source: https://context7.com/connorferster/forallpeople/llms.txt

Enables the creation of custom unit environments by defining JSON files that specify dimension vectors and conversion factors for new units. These custom environments can then be loaded into the forallpeople library, making the new units available for use in calculations.

```json
{
    "kPa": {
        "Dimension": [1,-1,-2,0,0,0,0],
        "Value": 1000
    },
    "MPa": {
        "Dimension": [1,-1,-2,0,0,0,0],
        "Value": 1000000
    },
    "lb": {
        "Dimension": [1,1,-2,0,0,0,0],
        "Factor": "1/0.45359237/9.80665",
        "Symbol": "lb"
    },
    "ft": {
        "Dimension": [0,1,0,0,0,0,0],
        "Factor": "1/0.3048",
        "Symbol": "ft"
    },
    "psi": {
        "Dimension": [1,-1,-2,0,0,0,0],
        "Factor": "0.0254**2/0.45359237/9.80665",
        "Symbol": "psi"
    }
}
```

```python
# Save as 'my_env.json' in forallpeople/environments/
# Then load it:
import forallpeople as si
si.environment('my_env')

# Now custom units are available
force = 100 * si.lb
print(force)  # Output: 100.000 lb

length = 10 * si.ft
print(length)  # Output: 10.000 ft
```