Equations and mathematical expressions
Use equations and mathematical expressions only in technical and mathematical content when it's essential to convey meaning.
Equations (or formulas) are formal mathematical statements that usually include an equal sign, an approximately equal sign (≈), a not-equal sign (≠), or an inequality sign (<, ≤, >, or ≥). For example, the following statement is an equation:
2 + 3 = 5
Mathematical expressions are usually short statements that contain at least one value or variable. Often, expressions relate two or more values or variables via an operator, but without an equal sign. For example, 2 + 3 is an expression.
Determine whether an equation or expression is necessary
Use equations and mathematical expressions only when essential to help the reader understand something that they have control of.
note
Consider accessibility when deciding whether to include equations and expressions in your content. Don't create equations as images and embed them in your content. Text in images is inaccessible to users using screen readers. Writing equations using text and HTML entities is slightly more accessible, but screen readers often don't pronounce punctuation marks such as plus and equal signs. For this reason, keep equations to a minimum in your content.
Use equations or expression to explain how a user can change their behavior or update their application to acheive a different result. For example, you can use an expression to explain how a cost or a rate changes based on different inputs or conditions that the user has control over.
Don't use equations to indicate the way that Unity implements a particular computation or physical simulation. If the user needs to know the implementation details, then summarize the information in plain English and link to another source, such as a journal or archive paper. For more information on linking to external resources, refer to Links and citations.
If you're presenting the code representation of an equation rather than the mathematical statement itself, then write the expression as a code sample. For guidance on writing code samples, refer to Code examples.
If you're not sure if an equation or expression is essential, contact the #unity-style-guide channel.
Formatting equations and mathematical expressions
Write equations and expressions using only text and HTML entities. Don't create equations or expressions as images and embed them in your content. For a list of HTML entities you can use in your equations, refer to List of mathematical operators and symbols.
Use a space between each number, variable, and symbol.
Write equations and long expressions on a new line. You can write short mathematical expressions, such as definitions of variables, in-line as part of the body text.
Punctuate expressions that are part of body text. Don't use punctuation at the end of equations and expressions that are on separate lines.
For operators that take an argument, write the argument in parentheses next to the operator. Don't use a space between the operator and the parentheses. For example, write "sin(x)."
Use subscripts and superscripts as necessary to identify variables or limits. Don't use spaces in subscripts and superscripts. Avoid using subscripts and superscripts on the same variable. Instead, simplify the notation or write the details in the body text.
You can't format fractions in equations or expressions. Instead, use parentheses and the division sign to make the statement clear.
| Incorrect | Correct |
|---|---|
| Calculate speed using the formula v = d/t, where d is the distance and t is the time taken | Calculate speed using the formula v = d ÷ t where d is the distance and t is the time taken. |
| log10 (x) | log10(x) |
| ∑ni=m ai | ∑ai, where m ≤ i ≤ n |
Variables
Where possible, write variables as words, especially in content where readers might not be familiar with symbolic mathematics. For simple equations, you can use multiple lowercase words with spaces. In expressions with more than one operator, write words without any spaces, starting each word with a capital letter (Pascal case). You can use abbreviations in variable names. Don't use numbers in variable names.
Write variables as symbols in complex expressions where words make the expression difficult to read, or in technical content where you expect the reader to be familiar with symbolic mathematics.
For symbolic variables, try to use letters or symbols that relate to the quantity, such as d for distance or t for time. For a list of symbols and their typical usage as variables, refer to List of common conventions for variables.
If you use a symbol as a variable, define the variable in the text before or after the equation or expression.
If you need to differentiate similar symbolic variables, use subscripts. Don't use subscripts with variables that are words.
In general, use lowercase letters as symbols for scalar (non-vector) variables, unless the use of a single uppercase letter is standard in the relevant technical literature.
| Incorrect | Correct |
|---|---|
| $5 × n | $5 × number of installs |
| rate = #clicks ÷ #impressions | conversion rate = number of clicks ÷ number of impressions |
| ORGBA = SRGB + DRGBA × (1 − SA) | OutputRGBA = SourceRGB + DestinationRGB × (1 − SourceAlpha) |
| x = sin(angle1)cos(angle2) | x = sin(θ)cos(φ) |
Vectors and quaternions
note
Unity uses a left-handed coordinate system for the orientation of the x, y, and z component of three-vectors. If you need to demonstrate vector multiplication, make sure that you follow the rules for left-handed coordinate systems (Microsoft).
Write vector and quaternion variables as capital letters in bold. Write the component values of vectors and quaternions as lowercase letters with no formatting. Don't write vectors or quaternions or their components as words.
Write unit vectors with a bold u. If you need to indicate the basis vector in each dimension, use a bold e with a subscript to indicate the dimension.
For quaternions, write the scalar part w as the final component of the quaternion.
| Type | Example |
|---|---|
| two-vector | A = xex + yey |
| three-vector | B = xex + yey + zez |
| four-vector | C = xex + yey + zez + wew |
| quaternion | D = xex + yey + zez + w |
List of mathematical operators and symbols
The following table indicates common mathematical operators and symbols that you can use in your technical content.
Use the correct HTML entity or Unicode character for each symbol. Don't substitute symbols using punctuation available on a standard keyboard. For example, don't substitute an asterisk for the multiplication symbol, a slash for the divide symbol, or a tilde for the approximately equal symbol.
| Operator | Symbol | HTML entity |
|---|---|---|
| plus | + | |
| minus | − | − |
| multiply | × | × |
| divide | ÷ | ÷ |
| equal | = | |
| approximately equal | ≈ | ≈ |
| not equal | ≠ | ≠ |
| less than | < | < |
| less than or equal | ≤ | ≤ |
| greater than | > | > |
| greater than or equal | ≥ | ≥ |
| left parenthesis | ( | |
| right parenthesis | ) | |
| exponent superscript | xn | x<sup>n</sup> |
| subscript | xi | x<sub>i</sub> |
| sum | ∑ | ∑ |
| dot product Use only in vector-related content. | ⋅ | ⋅ |
| cross product | × | × |
| logarithm Use ln for logarithms with base e. Use logm for logarithms with base m. | ln(x) logm(x) | |
| degrees | ° | ° |
| pi | π | π |
List of common conventions for variables
The following table lists some common conventions for mathematical notation. Where possible, follow these conventions in your technical content.
This list isn't exhaustive. If the relevant technical literature follows different conventions that you expect most readers are familiar with, then use those conventions instead.
| Letter | HTML entity | Usage notes |
|---|---|---|
| a, b, c, d | Use as general variables to represent any scalar quantities and measurements. In optics-related content, use c only to refer to the speed of light. | |
| A, B, C, D | Use as general variables to represent any vector quantities and measurements. | |
| e | Don't use as a variable. Use only to refer to Euler's number (the base of natural logarithms). You don't need to define e in your body text. | |
| ei | Use to represent the basis vectors of the coordinate system. | |
| i, j, k | Use as indices for variables that are part of a set. Write indices as subscripts on a variable. For example, ai. The letters i and j can represent the imaginary unit. Complex numbers aren't available in Unity, so make sure that your content can't be misunderstood. | |
| m, n | Use to represent dimensionless numbers. In other words, values without units. Use as upper and lower bounds for index values. For example, m ≤ i ≤ n. | |
| t | Use as a variable to represent a quantity of time. | |
| T | Use as a variable to represent a temperature in degrees Celcius. | |
| u | Use to represent a unit vector in a specific direction. | |
| v | Use as a variable to represent speed. | |
| V | Use as a variable to represent a velocity vector (speed in a specific direction). | |
| w, x, y, z | Use as general variables to represent any quantities and measurements, especially distances. Use w, x, y, z to refer to the components of vectors and quaternions. | |
| π (pi) | π | Use only for the circle constant. You don't need to define π in your body text. |
| θ (theta) | θ | Use only as a variable to represent an angle expressed in radians. |
| φ (phi) | φ | Use only as a variable to represent an angle expressed in radians. |