# Variable naming syntax

CalcTree variables use custom syntax that let you create variables that work as functional calculations (in 'code-friendly' form) while displaying also rendering as clean mathematical notation. This system uses underscores and special keywords to control subscripts, superscripts, mathematical symbols, and other formatting.

### Basic Concepts

#### Simple Names

* **Regular variable names display as-is:**
  * `velocity` → $$velocity$$
  * `force` → $$force$$
  * `temperature` → $$temperature$$
* **Names ending with underscore use regular font with spaces:**
  * `total_cost_` → $$total \space cost$$
  * `heat_flow_rate_` → $$heat \space flow \space rate$$
  * `max_speed_` → $$max \space speed$$
  * Note: The trailing underscore converts underscores to spaces

#### Special Separators

**Single Underscore `_` Rules**

A single underscore has different meanings depending on what follows it:

**For regular text - creates subscripts:**

* `v_max` → $$v\_{max}$$
* `F_applied` → $$F\_{applied}$$
* `x_1` → $$x\_1$$

**For Greek keywords - converts and subscripts:**

* `alpha_1` → $$\alpha\_1$$ (converts 'alpha' to α and subscripts '1')
* `sigma_yield` → $$\sigma\_{yield}$$(converts 'sigma' to σ and subscripts 'yield')

**For special keywords - triggers special formatting:**

* `x_prm` → $$x'$$ (prime right notation)
* `prm_x` → $$'x$$ (prime left notation)
* `ovr_x` → $$x̄$$ (overline for averages)

**Combined with double underscore for superscripts:**

* `x_1__2` → x<sub>1</sub><sup>2</sup> (x subscript 1, squared)
* `v_final__2` → v<sub>final</sub><sup>2</sup> (final velocity squared)

### Formatting Syntax

#### **Subscripts and Superscripts**

Use underscores followed by special placeholders:

<table><thead><tr><th>Syntax</th><th width="180">Result</th><th>Example</th></tr></thead><tbody><tr><td><code>name_text</code></td><td>Subscript</td><td><code>v_max</code>  → <span class="math">v_{max}</span></td></tr><tr><td><code>name__text</code></td><td>Superscript</td><td><code>x__2</code>  → <span class="math">x^2</span></td></tr><tr><td><code>name_sub__sup</code></td><td>Both</td><td><code>x_i__2</code> → <span class="math">x_i^2</span></td></tr></tbody></table>

### Complete **Mathematical** Symbol Reference

CalcTree automatically converts certain keywords to mathematical symbols when a variable is rendered on the page:

#### **Lowercase Greek**

| Keyword   | Symbol | Example             | Display                   |
| --------- | ------ | ------------------- | ------------------------- |
| `alpha`   | α      | `alpha_1`           | $$\alpha\_{1}$$           |
| `beta`    | β      | `beta_coefficient`  | $$\beta\_{coefficient}$$  |
| `gamma`   | γ      | `gamma_ray`         | $$\gamma\_{ray}$$         |
| `delta`   | δ      | `delta_t`           | $$\delta\_{t}$$           |
| `epsilon` | ε      | `epsilon_0`         | $$\epsilon\_{0}$$         |
| `zeta`    | ζ      | `zeta_function`     | $$\zeta\_{function}$$     |
| `eta`     | η      | `eta_efficiency`    | $$\eta\_{efficiency}$$    |
| `theta`   | θ      | `theta_angle`       | $$\theta\_{angle}$$       |
| `iota`    | ι      | `iota_value`        | $$\iota\_{value}$$        |
| `kappa`   | κ      | `kappa_constant`    | $$\kappa\_{constant}$$    |
| `lambda`  | λ      | `lambda_wavelength` | $$\lambda\_{wavelength}$$ |
| `mu`      | μ      | `mu_friction`       | $$\mu\_{friction}$$       |
| `nu`      | ν      | `nu_frequency`      | $$\nu\_{frequency}$$      |
| `xi`      | ξ      | `xi_parameter`      | $$\xi\_{parameter}$$      |
| `omicron` | ο      | `omicron_value`     | $$\omicron\_{value}$$     |
| `pi`      | π      | `pi_constant`       | $$\pi\_{constant}$$       |
| `rho`     | ρ      | `rho_density`       | $$\rho\_{density}$$       |
| `sigma`   | σ      | `sigma_stress`      | $$\sigma\_{stress}$$      |
| `tau`     | τ      | `tau_torque`        | $$\tau\_{torque}$$        |
| `upsilon` | υ      | `upsilon_velocity`  | $$\upsilon\_{velocity}$$  |
| `phi`     | φ      | `phi_angle`         | $$\phi\_{angle}$$         |
| `chi`     | χ      | `chi_squared`       | $$\chi\_{squared}$$       |
| `psi`     | ψ      | `psi_wave`          | $$\psi\_{wave}$$          |
| `omega`   | ω      | `omega_angular`     | $$\omega\_{angular}$$     |

#### **Uppercase Greek**

| Keyword   | Symbol | Example              | Display                    |
| --------- | ------ | -------------------- | -------------------------- |
| `Alpha`   | Α      | `Alpha_particle`     | $$\Alpha\_{particle}$$     |
| `Beta`    | Β      | `Beta_function`      | $$\Beta\_{function}$$      |
| `Gamma`   | Γ      | `Gamma_distribution` | $$\Gamma\_{distribution}$$ |
| `Delta`   | Δ      | `Delta_H`            | $$\Delta\_{H}$$            |
| `Epsilon` | Ε      | `Epsilon_field`      | $$\Epsilon\_{field}$$      |
| `Zeta`    | Ζ      | `Zeta_potential`     | $$\Zeta\_{potential}$$     |
| `Eta`     | Η      | `Eta_meson`          | $$\Eta\_{meson}$$          |
| `Theta`   | Θ      | `Theta_temperature`  | $$\Theta\_{temperature}$$  |
| `Iota`    | Ι      | `Iota_index`         | $$\Iota\_{index}$$         |
| `Kappa`   | Κ      | `Kappa_number`       | $$\Kappa\_{number}$$       |
| `Lambda`  | Λ      | `Lambda_baryon`      | $$\Lambda\_{baryon}$$      |
| `Mu`      | Μ      | `Mu_mass`            | $$\Mu\_{mass}$$            |
| `Nu`      | Ν      | `Nu_neutrino`        | $$\Nu\_{neutrino}$$        |
| `Xi`      | Ξ      | `Xi_cascade`         | $$\Xi\_{cascade}$$         |
| `Omicron` | Ο      | `Omicron_variant`    | $$\Omicron\_{variant}$$    |
| `Pi`      | Π      | `Pi_product`         | $$\Pi\_{product}$$         |
| `Rho`     | Ρ      | `Rho_meson`          | $$\Rho\_{meson}$$          |
| `Sigma`   | Σ      | `Sigma_sum`          | $$\Sigma\_{sum}$$          |
| `Tau`     | Τ      | `Tau_lepton`         | $$\Tau\_{lepton}$$         |
| `Upsilon` | Υ      | `Upsilon_meson`      | $$\Upsilon\_{meson}$$      |
| `Phi`     | Φ      | `Phi_flux`           | $$\Phi\_{flux}$$           |
| `Chi`     | Χ      | `Chi_distribution`   | $$\Chi\_{distribution}$$   |
| `Psi`     | Ψ      | `Psi_function`       | $$\Psi\_{function}$$       |
| `Omega`   | Ω      | `Omega_resistance`   | $$\Omega\_{resistance}$$   |

#### **Greek Variations**

| Keyword      | Symbol          | Description     |
| ------------ | --------------- | --------------- |
| `varepsilon` | $$\varepsilon$$ | Variant epsilon |
| `varkappa`   | $$\varkappa$$   | Variant kappa   |
| `varphi`     | $$\varphi$$     | Variant phi     |
| `varpi`      | $$\varpi$$      | Variant pi      |
| `varrho`     | $$\varrho$$     | Variant rho     |
| `varsigma`   | $$\varsigma$$   | Variant sigma   |
| `vartheta`   | $$\vartheta$$   | Variant theta   |

#### **Special Mathematical Symbols**

| Keyword    | Symbol | Example       | Display              |
| ---------- | ------ | ------------- | -------------------- |
| `infty`    | ∞      | `T_infty`     | $$T\_{\infty}$$      |
| `diameter` | ⌀      | `d_diameter`  | $$d\_{\varnothing}$$ |
| `circ`     | °      | `angle_circ`  | $$angle\_{\circ}$$   |
| `mid`      | \|     | `x_mid`       | $$x\_{\mid}$$        |
| `degree`   | °      | `temp_degree` | $$temp\_{\degree}$$  |
| `star`     | ⋆      | `rating_star` | $$rating\_{\star}$$  |

#### **Punctuation & Operators**

These symbols are inserted in the baseline (not as subscripts) when preceded by a single underscore:

| Keyword | Symbol  | Example          | Display          |
| ------- | ------- | ---------------- | ---------------- |
| `prm`   | '       | `x_prm`          | $$x'$$           |
| `dot`   | .       | `v_dot`          | $$\dot{v}$$      |
| `cma`   | ,       | `item_cma_1`     | $$item, 1$$      |
| `div`   | /       | `m_div_s`        | $$m/s$$          |
| `spc`   | (space) | `total_spc_cost` | $$total ; cost$$ |
| `num`   | #       | `item_num_5`     | $$item#5$$       |
| `pls`   | +       | `charge_pls`     | $$charge+$$      |
| `mns`   | -       | `ion_mns`        | $$ion-$$         |

#### **Special Directives**

These create formatting effects:

| Keyword | Effect      | Example      | Display          |
| ------- | ----------- | ------------ | ---------------- |
| `sqrt`  | Square root | `value_sqrt` | $$\sqrt{value}$$ |
| `prn`   | Parentheses | `sum_prn`    | $$(sum)$$        |
| `ovr`   | Overline    | `x_ovr`      | $$\overline{x}$$ |

**Advanced Formatting**

Special placeholder keywords after underscores:

### Examples

### Engineering Variables

**Stress components:**

* `sigma_xx` → $$\sigma\_{xx}$$ (sigma with xx subscript)
* `sigma_y__2` → $$\sigma\_{y}^{2}$$ (sigma with y subscript and squared)
* `tau_xy` → $$\tau\_{xy}$$ (shear stress)

**Heat transfer:**

* `q_dot_` → $$q ; dot$$ (heat flux, regular font)
* `T_infty` → $$T\_{\infty}$$ (temperature at infinity)
* `alpha_thermal` → $$\alpha\_{thermal}$$ (thermal diffusivity)

**Electrical:**

* `V_rms` → $$V\_{rms}$$ (RMS voltage)
* `I_peak__2` → $$I^{2}\_{peak}$$ (peak current squared)
* `Omega_resistance` → $$\Omega\_{resistance}$$ (resistance in ohms)

### Physics & Mathematics

**Wave functions:**

* `psi_n` → $$\psi\_{n}$$ (wave function n)
* `Psi_total` → $$\Psi\_{total}$$ (total wave function)

**Statistics:**

* `mu_population` → $$\mu\_{population}$$ (population mean)
* `sigma_x` → $$\sigma\_{x}$$ (standard deviation)
* `chi__2` → $$\chi^{2}$$ (chi-squared)

**Calculus:**

* `Delta_x` → $$\Delta\_{x}$$ (change in x)
* `epsilon_0` → $$\epsilon\_{0}$$ (permittivity of free space)

### Reserved Keywords

These words **cannot** be used as variable names:

**MathJS Reserved:** `mod`, `to`, `in`, `and`, `xor`, `or`, `not`, `end`

**Python Reserved (for compatibility):** `False`, `None`, `True`, `and`, `as`, `assert`, `async`, `await`, `break`, `class`, `continue`, `def`, `del`, `elif`, `else`, `except`, `finally`, `for`, `from`, `global`, `if`, `import`, `in`, `is`, `lambda`, `nonlocal`, `not`, `or`, `pass`, `raise`, `return`, `try`, `while`, `with`, `yield`

### Best Practices

1. **Use meaningful base names:** `sigma_yield` is better than just `sigma`
2. **Be consistent:** Use the same naming patterns throughout your project
3. **Consider context:** `Delta_T` for temperature change, `delta_small` for small changes
4. **Mix symbols wisely:** `alpha_beta_ratio` → $$\alpha\_{beta\_ratio}$$ (only first part converts)

### Quick Reference Card

* **Basic subscript:** `variable_subscript` → $$variable\_{subscript}$$
* **Basic superscript:** `variable__superscript` → $$variable^{superscript}$$
* **Both:** `variable_sub__sup` → $$variable\_{sub}^{sup}$$
* **Greek letter:** `alpha_1` → $$\alpha\_{1}$$
* **Uppercase Greek:** `Delta_x` → $$\Delta\_{x}$$
* **Regular font (spaces):** `my_variable_` → $$my ; variable$$
* **Overline:** `x_ovr` → $$\overline{x}$$
* **Square root:** `value_sqrt` → $$\sqrt{value}$$
* **Parentheses:** `term_prn` → $$(term)$$
* **Prime notation:** `x_prm` → $$x'$$
* **Infinity:** `T_infty` → $$T\_{\infty}$$
* **Multi-part:** `part1_bsl_part2` → $$part1/part2$$

#### Troubleshooting

**Variable not displaying as expected?**

* Check if you're using the correct number of underscores
* Verify the keyword is in the supported symbols list
* Ensure no typos in placeholder keywords

**Calculation errors?**

* Confirm the base name is a valid identifier
* Check for reserved keywords conflict
* Verify syntax without special formatting first
