UzonCalc User Guide

UzonCalc is a Python-based tool for hand-written engineering calculation reports. Focus on content and calculation logic; UzonCalc handles result rendering, formatting, and typesetting. It supports units, Excel calls, tables, charts, and more, enabling reuse of existing Excel models.

Features

1. Write calculation reports using Pythonsimple and expressive

2. AI-friendly: Python works well with AI assistance

3. All operations are functions, easy to understand and use

4. Automatically substitute and display computed values

5. Focus on logic; UzonCalc handles the dirty work

6. Unit-aware calculations with automatic conversions and checks

7. Call Excel calculations to reuse existing models

8. Output to HTML for viewing and printing to PDF/Word

9. Highly customizable with templates and styles

10. Open-source (MIT)

Getting started: basic Python syntax and conventions useful for UzonCalc

Installation and Usage

Install via pip:

pip install uzoncalc

A simple example script is as follows:

from uzoncalc import *

@uzon_calc()
def sheet():
    doc_title("uzoncalc example")

    "Hello, UzonCalc!"

    save()


if __name__ == "__main__":
    sheet()

Run the script with:

python example.py

Python Basics

Here are some Python basics to help you get started with UzonCalc.

1. Strings: use single, double, or triple quotes

2. Numbers: integers and floats (e.g. 42, 3.14)

3. Booleans: True and False

4. Lists: use [ ] for lists, e.g. [1,2,3]

5. Assignment: use = to assign values

6. Operators: +, -, *, /, ** for math; comparison operators available

7. Variable names: letters, digits and underscores; cannot start with digit

8. Indentation: use 4 spaces for blocks

9. Comments: start with #

Coding suggestions:

- Prefer English names for variables

- Use camelCase for variable names (UzonCalc treats _ as subscript)

- Add comments where helpful

- Keep functions small and focused

Automatic Table of Contents

Call `toc()` to automatically generate the document contents here.

Variables and Naming

Naming rules

Variable names can include letters, digits and underscores but cannot start with a digit.

Use camelCase in UzonCalc to avoid conflict with subscript notation.

Aliases

You can define display aliases for variables. Aliases may include non-ASCII characters.

age_xm = 30
alias("age_xm", "Person's age")
age_xm
name_xm = "Xiao Ming"
alias("name_xm", "Name_XiaoMing")
name_xm

${\mathit{age}}_{\text{xm}}=30$

$\mathit{Person\text{'}s\; age}=30$

${\mathit{name}}_{\text{xm}}=\text{Xiao Ming}$

${\mathit{Name}}_{\text{XiaoMing}}=\text{Xiao Ming}$

You can remove an alias by setting it to None.

${\mathit{Name}}_{\text{XiaoMing}}=\text{Xiao Ming}$

${\mathit{age}}_{\text{xm}}=30$

Strings

Single, double or triple quotes can be used to output paragraphs.

'single quoted'

"double quoted"

"""
Triple quoted text becomes a paragraph when rendered.
"""

single quoted

double quoted

Triple quoted text becomes a paragraph when rendered.

Numbers

# integer
integerNumber = 100
# float
floatNumber = 3.1415
# scientific
scientificNumber = 1.2e3
# complex
complexNumber = 2 + 3j

$\mathit{integerNumber}=100$

$\mathit{floatNumber}=3.1415$

$\mathit{scientificNumber}=1200.0=1200$

$\mathit{complexNumber}=2+\text{3j}=\text{(2+3j)}$

Tensors / Arrays

UzonCalc supports NumPy for tensor/matrix operations.

$\mathbf{arr}=\text{np.array}\left([[1,2,3],[4,5,6]]\right)=[[1,2,3],[4,5,6]]$

$\mathbf{firstRow}={\mathbf{arr}}_{0,:}=[1,2,3]$

$\mathbf{secondColumn}={\mathbf{arr}}_{:,1}=[2,5]$

$\mathit{firstCell}={\mathbf{arr}}_{0,0}=\text{1}$

Units

Using units

UzonCalc uses pint for unit handling. Use `unit.*` to access units.

l_cp = 5 * unit.meter
w_cp = 10 * unit.m
h_cp = 2 * unit.meter
v_cp = l_cp * w_cp * h_cp

${\mathit{l}}_{\text{cp}}=5\mathrm{\text{m}}$

${\mathit{w}}_{\text{cp}}=10\mathrm{\text{m}}$

${\mathit{h}}_{\text{cp}}=2\mathrm{\text{m}}$

${\mathit{v}}_{\text{cp}}={\mathit{l}}_{\text{cp}}·{\mathit{w}}_{\text{cp}}·{\mathit{h}}_{\text{cp}}=5\mathrm{\text{m}}·10\mathrm{\text{m}}·2\mathrm{\text{m}}=100\mathrm{\text{m³}}$

force = 100 * unit.newton
A_top = l_cp * w_cp
stress_cp = force / A_top

$\mathit{force}=100\mathrm{\text{N}}$

${\mathit{A}}_{\text{top}}={\mathit{l}}_{\text{cp}}·{\mathit{w}}_{\text{cp}}=5\mathrm{\text{m}}·10\mathrm{\text{m}}=50\mathrm{\text{m²}}$

${\mathit{stress}}_{\text{cp}}=\frac{\mathit{force}}{{\mathit{A}}_{\text{top}}}=\frac{100\mathrm{\text{N}}}{50\mathrm{\text{m²}}}=2\mathrm{\text{N/m²}}$

Unit calculations

You can perform arithmetic directly on quantities with units.

sqrtArea = sqrt(A_top + 10 * unit.meter**2)
acceleration = force * 1000 / (10 * unit.kilogram)

$\mathit{sqrtArea}=\sqrt{{\mathit{A}}_{\text{top}}+10\mathrm{\text{m²}}}=\sqrt{50\mathrm{\text{m²}}+10\mathrm{\text{m²}}}=7.745966692415\mathrm{\text{m}}$

$\mathit{acceleration}=\frac{\mathit{force}·1000}{10\mathrm{\text{kg}}}=\frac{100\mathrm{\text{N}}·1000}{10\mathrm{\text{kg}}}=10000\mathrm{\text{N/kg}}$

Unit conversion

originalSpeed = 18 * unit.meter / unit.second
speedKmh = originalSpeed.to(unit.kilometer / unit.hour)
"Original speed (m/s):"
originalSpeed
"Converted speed (km/h):"
speedKmh

$\mathit{originalSpeed}=18\mathrm{\text{m/s}}$

$\mathit{speedKmh}=\text{originalSpeed.to}\left(\mathrm{\text{km/h}}\right)=64.8\mathrm{\text{km/h}}$

Original speed (m/s):

$\mathit{originalSpeed}=18\mathrm{\text{m/s}}$

Converted speed (km/h):

$\mathit{speedKmh}=64.8\mathrm{\text{km/h}}$

Advanced String Usage

Formatting

You can use f-strings for formatting.

name = "Uzon"
f"Hello, {name}! Welcome to UzonCalc."
π = 3.1415926535
f"Value of pi up to 3 decimal places: {pi:.3f}"

$\mathit{name}=\text{Uzon}$

Hello, $\text{Uzon}$! Welcome to UzonCalc.

$\mathit{\pi }=3.1415926535$

Value of π up to 3 decimal places: $\text{3.142}$

Show equations in f-strings

Enable equation display inside f-strings with `enable_fstring_equation()` and disable with `disable_fstring_equation()`.

Hello, $\mathit{name}=\text{Uzon}$! Welcome to UzonCalc.

The value of π is approximately $\mathit{\pi }=\text{3.142}$, which is useful in calculations.

Operators

Use standard arithmetic and comparison operators.

$\mathit{operatorResult}=\left(5+3\right)·2-\frac{4}{2^2}=15$

$\mathit{comparisonResult}=5>3\wedge 2\equiv 2\vee 4\ne 5=\mathrm{True}$

Plotting

You can create plots using Matplotlib inside UzonCalc.

hide()
import matplotlib.pyplot as plt
x = np.linspace(0, 2 * np.π, 100)
y = np.sin(x)
plt.plot(x, y)
plt.title("Sine Wave")
plt.xlabel("x (radians)")
plt.ylabel("sin(x)")
plt.legend(["sin(x)"])
plt.grid(True)
show()
Plot(plt)

Subscripts

Default rule

Use underscore to indicate subscript in rendered names, e.g. H_2 becomes H.

${\mathit{a}}_{\text{x}}=10\mathrm{\text{m/s²}}$

${\mathit{speed}}_{\text{car}}={\mathit{a}}_{\text{x}}·2·\mathrm{\text{second}}=10\mathrm{\text{m/s²}}·2·\mathrm{\text{second}}=20\mathrm{\text{m/s}}$

Complex subscripts

Python identifiers cannot contain non-ASCII characters, but you can use aliases for display.

${\mathit{speed}}_{\text{汽车}}=20\mathrm{\text{m/s}}$

$\mathit{distance}={\mathit{speed}}_{\text{汽车}}·5·\mathrm{\text{second}}=20\mathrm{\text{m/s}}·5·\mathrm{\text{second}}=100\mathrm{\text{m}}$

Alias removed; variable displays its original name

${\mathit{speed}}_{\text{car}}=20\mathrm{\text{m/s}}$

Array subscripts

Square bracket contents are treated as subscripts for arrays.

$\mathbf{arr2d}=\text{np.array}\left([[1,2,3],[4,5,6]]\right)=[[1,2,3],[4,5,6]]$

$\mathbf{firstRow}={\mathbf{arr2d}}_{0,:}=[1,2,3]$

$\mathbf{secondColumn}={\mathbf{arr2d}}_{:,1}=[2,5]$

$\mathit{firstCell}={\mathbf{arr2d}}_{0,0}=\text{1}$

Greek letters

Use names like 'alpha', 'beta', 'gamma' to render Greek letters. Capitalized names render uppercase Greek letters.

${\mathit{\rho }}_{\text{water}}=1000\mathrm{\text{kg/m³}}$

${\mathit{\gamma }}_{\text{0}}=9.81\mathrm{\text{m/s²}}$

Function converters

Functions like sqrt and abs are rendered in math style.

$\mathit{edge1}=3\mathrm{\text{m}}$

$\mathit{edge2}=4\mathrm{\text{m}}$

$\mathit{diagonal}=\sqrt{{\mathit{edge1}}^2+{\mathit{edge2}}^2}=\sqrt{{\left(3\mathrm{\text{m}}\right)}^2+{\left(4\mathrm{\text{m}}\right)}^2}=5\mathrm{\text{m}}$

$\mathit{value}=-15\mathrm{\text{N}}$

$\mathit{absValue}=\left|\mathit{value}\right|=\left|-15\mathrm{\text{N}}\right|=15\mathrm{\text{N}}$

Tables

Tables can be created with `Table()`; headers can use rowspan/colspan.

Example Table

Component	Material	Elastic Modulus (MPa)		Design Strength (MPa)		Standard Strength (MPa)
		Ec/Es	Compressive	Tensile	Compressive	Tensile
		Cap Beam	C60	36000.0	26.5	1.96	38.5	2.85
Cap Beam 2	C60	36000.0	26.5	1.96	38.5	2.85

Calling Excel calculations

You can update cell values in an Excel workbook and retrieve the result table.

Solid Params
Width	Length	Height	Volume
6	10	2	240

By default, Excel results are cached when inputs do not change to speed up rendering.

Saving the document

Save as HTML

Use `save()` to export the document to an HTML file.

Print to PDF

Open the generated HTML in a browser and use the print feature to save as PDF.

Export to Word

You can convert HTML to Word using pandoc.