20 KiB
markup, title, description
| markup | title | description |
|---|---|---|
| occlusion | lib/math | High-school math — num, random, formula, plot |
High-school math — num, random, formula, plot
Compute numbers, symbolic expressions and plots.
Behavior and limits: Number contracts include symbolic formulas. Random values require random.read. Plotting emits an artifact and needs output.write; linear algebra and quantum workloads stay in ext.
This single source file is the usage and development manual. Import it directly, or use marqdo call with a function heading below. Parameter tables give types and defaults; required parameters must be supplied. Return tables are progressive contracts; prose describes failure and limits.
Implementation: src/host/math.rs
For development, keep EN/ZH behavior aligned and compose public libraries first. Add host primitives only at OS or algorithm boundaries and declare their effects. Run marqdo check --narrative-ratio on this file and the real workflows in tests/stdlib_tasks.rs after edits.
pi
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Return the mathematical constant pi |
Effects: pure.
Return the mathematical constant pi.
Return Return the mathematical constant pi.
e
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Return Euler constant e |
Effects: pure.
Return Euler constant e.
Return Return Euler constant e.
num
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Convert a numeric value or numeric text to a number |
Use value as the inputs for this operation.
Effects: pure.
Convert a numeric value or numeric text to a number.
Return [Convert a numeric value or numeric text to a number](> host_num value=value).
add
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | required | First operand; its domain is described by this operation |
| b | any | required | Second operand; its domain is described by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Add the two numeric or symbolic operands |
Use a, b as the inputs for this operation.
Effects: pure.
Add the two numeric or symbolic operands.
Return [Add the two numeric or symbolic operands](> host_math_add a=a b=b).
sub
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | required | First operand; its domain is described by this operation |
| b | any | required | Second operand; its domain is described by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Subtract b from a |
Use a, b as the inputs for this operation.
Effects: pure.
Subtract b from a.
Return [Subtract b from a](> host_math_sub a=a b=b).
mul
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | required | First operand; its domain is described by this operation |
| b | any | required | Second operand; its domain is described by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Multiply a by b |
Use a, b as the inputs for this operation.
Effects: pure.
Multiply a by b.
Return [Multiply a by b](> host_math_mul a=a b=b).
div
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | required | First operand; its domain is described by this operation |
| b | any | required | Second operand; its domain is described by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Divide a by b; zero divisor is an error |
Use a, b as the inputs for this operation.
Effects: pure.
Divide a by b; zero divisor is an error.
Return [Divide a by b; zero divisor is an error](> host_math_div a=a b=b).
pow
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | required | First operand; its domain is described by this operation |
| b | any | required | Second operand; its domain is described by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Raise a to the power b |
Use a, b as the inputs for this operation.
Effects: pure.
Raise a to the power b.
Return [Raise a to the power b](> host_math_pow a=a b=b).
neg
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Negate a numeric or symbolic value |
Use value as the inputs for this operation.
Effects: pure.
Negate a numeric or symbolic value.
Return [Negate a numeric or symbolic value](> host_math_neg value=value).
sin
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Compute sine; numeric angles are radians |
Use value as the inputs for this operation.
Effects: pure.
Compute sine; numeric angles are radians.
Return [Compute sine; numeric angles are radians](> host_math_sin value=value).
cos
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Compute cosine; numeric angles are radians |
Use value as the inputs for this operation.
Effects: pure.
Compute cosine; numeric angles are radians.
Return [Compute cosine; numeric angles are radians](> host_math_cos value=value).
tan
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Compute tangent; numeric angles are radians |
Use value as the inputs for this operation.
Effects: pure.
Compute tangent; numeric angles are radians.
Return [Compute tangent; numeric angles are radians](> host_math_tan value=value).
asin
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Compute arcsine in radians |
Use value as the inputs for this operation.
Effects: pure.
Compute arcsine in radians.
Return [Compute arcsine in radians](> host_math_asin value=value).
acos
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Compute arccosine in radians |
Use value as the inputs for this operation.
Effects: pure.
Compute arccosine in radians.
Return [Compute arccosine in radians](> host_math_acos value=value).
atan
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Compute arctangent in radians |
Use value as the inputs for this operation.
Effects: pure.
Compute arctangent in radians.
Return [Compute arctangent in radians](> host_math_atan value=value).
sqrt
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Compute the square root of value |
Use value as the inputs for this operation.
Effects: pure.
Call this function directly:
marqdo call lib/math.mq.md sqrt value=9 --effects none --json
Compute the square root of value.
Return [Compute the square root of value](> host_math_sqrt value=value).
abs
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Return absolute magnitude |
Use value as the inputs for this operation.
Effects: pure.
Return absolute magnitude.
Return [Return absolute magnitude](> host_math_abs value=value).
ln
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Compute natural logarithm |
Use value as the inputs for this operation.
Effects: pure.
Compute natural logarithm.
Return [Compute natural logarithm](> host_math_ln value=value).
exp
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Compute the exponential of value |
Use value as the inputs for this operation.
Effects: pure.
Compute the exponential of value.
Return [Compute the exponential of value](> host_math_exp value=value).
floor
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Round toward negative infinity |
Use value as the inputs for this operation.
Effects: pure.
Round toward negative infinity.
Return [Round toward negative infinity](> host_math_floor value=value).
ceil
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Round toward positive infinity |
Use value as the inputs for this operation.
Effects: pure.
Round toward positive infinity.
Return [Round toward positive infinity](> host_math_ceil value=value).
min
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | required | First operand; its domain is described by this operation |
| b | any | required | Second operand; its domain is described by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Return the smaller operand |
Use a, b as the inputs for this operation.
Effects: pure.
Return the smaller operand.
Return [Return the smaller operand](> host_math_min a=a b=b).
max
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | required | First operand; its domain is described by this operation |
| b | any | required | Second operand; its domain is described by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Return the larger operand |
Use a, b as the inputs for this operation.
Effects: pure.
Return the larger operand.
Return [Return the larger operand](> host_math_max a=a b=b).
random
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Return a pseudo-random number; seed controls reproducibility |
Effects: random.read.
Return a pseudo-random number; seed controls reproducibility.
Return Return a pseudo-random number; seed controls reproducibility.
random_int
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| min | any | required | Inclusive lower bound or start of the search/plot interval |
| max | any | required | Upper bound or end of the search/plot interval |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Return a pseudo-random integer in the documented bounds |
Use min, max as the inputs for this operation.
Effects: random.read.
Return a pseudo-random integer in the documented bounds.
Return [Return a pseudo-random integer in the documented bounds](> host_random_int min=min max=max).
seed
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | required | Integer seed for reproducible random sequences |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Set this run pseudo-random generator seed; not suitable for secrets |
Use value as the inputs for this operation.
Effects: pure.
Set this run pseudo-random generator seed; not suitable for secrets.
Return [Set this run pseudo-random generator seed; not suitable for secrets](> host_seed value=value).
formula
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | any | required | Text supplied by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Parse expression text into a symbolic formula for later algebra or evaluation; invalid syntax produces a diagnostic |
Use text as the inputs for this operation.
Effects: pure.
Parse expression text into a symbolic formula for later algebra or evaluation; invalid syntax produces a diagnostic.
Return [Parse expression text into a symbolic formula for later algebra or evaluation; invalid syntax produces a diagnostic](> host_formula value=text).
simplify
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| formula | any | required | Symbolic formula returned by formula or a prior symbolic operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Return a simplified formula without changing the input; this is symbolic algebra, not numeric evaluation |
Use formula as the inputs for this operation.
Effects: pure.
Return a simplified formula without changing the input; this is symbolic algebra, not numeric evaluation.
Return [Return a simplified formula without changing the input; this is symbolic algebra, not numeric evaluation](> host_simplify value=formula).
expand
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| formula | any | required | Symbolic formula returned by formula or a prior symbolic operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Expand algebraic products and powers and return a new symbolic formula |
Use formula as the inputs for this operation.
Effects: pure.
Expand algebraic products and powers and return a new symbolic formula.
Return [Expand algebraic products and powers and return a new symbolic formula](> host_expand value=formula).
diff
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| formula | any | required | Symbolic formula returned by formula or a prior symbolic operation |
| var | any | required | Symbol name to differentiate, substitute, evaluate or solve for |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Differentiate the formula with respect to the named symbol and return a symbolic derivative |
Use formula, var as the inputs for this operation.
Effects: pure.
Differentiate the formula with respect to the named symbol and return a symbolic derivative.
Return [Differentiate the formula with respect to the named symbol and return a symbolic derivative](> host_diff formula=formula var=var).
subs
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| formula | any | required | Symbolic formula returned by formula or a prior symbolic operation |
| var | any | required | Symbol name to differentiate, substitute, evaluate or solve for |
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Substitute a symbol with the supplied value; return a number if fully reduced, otherwise a formula |
Use formula, var, value as the inputs for this operation.
Effects: pure.
Substitute a symbol with the supplied value; return a number if fully reduced, otherwise a formula.
Return [Substitute a symbol with the supplied value; return a number if fully reduced, otherwise a formula](> host_subs formula=formula var=var value=value).
eval
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| formula | any | required | Symbolic formula returned by formula or a prior symbolic operation |
| var | any | required | Symbol name to differentiate, substitute, evaluate or solve for |
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Evaluate a formula at one numeric variable value; unresolved symbols produce a diagnostic |
Use formula, var, value as the inputs for this operation.
Effects: pure.
Evaluate a formula at one numeric variable value; unresolved symbols produce a diagnostic.
Return [Evaluate a formula at one numeric variable value; unresolved symbols produce a diagnostic](> host_eval formula=formula var=var value=value).
solve
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| formula | any | required | Symbolic formula returned by formula or a prior symbolic operation |
| var | any | required | Symbol name to differentiate, substitute, evaluate or solve for |
| min | any | None | Inclusive lower bound or start of the search/plot interval |
| max | any | None | Upper bound or end of the search/plot interval |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Return roots for the named symbol within min and max; omitted bounds use -100 and 100 |
Use formula, var, min=None, max=None as the inputs for this operation.
Effects: pure.
Return roots for the named symbol within min and max; omitted bounds use -100 and 100.
Return [Return roots for the named symbol within min and max; omitted bounds use -100 and 100](> host_solve formula=formula var=var min=min max=max).
plot
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| formula | any | required | Symbolic formula returned by formula or a prior symbolic operation |
| var | any | required | Symbol name to differentiate, substitute, evaluate or solve for |
| min | any | required | Inclusive lower bound or start of the search/plot interval |
| max | any | required | Upper bound or end of the search/plot interval |
| steps | any | None | Number of samples across the plotting interval |
| path | any | None | Path relative to the granted filesystem root |
| derivative | any | None | Whether to include the derivative in the plot |
| grid | any | None | Whether to draw a coordinate grid |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Sample the formula over the interval and return SVG text; an optional path also writes the SVG under the granted root |
Use formula, var, min, max, steps=None, path=None, derivative=None, grid=None as the inputs for this operation.
Effects: output.write.
Sample the formula over the interval and return SVG text; an optional path also writes the SVG under the granted root.
Return [Sample the formula over the interval and return SVG text; an optional path also writes the SVG under the granted root](> host_plot formula=formula var=var min=min max=max steps=steps path=path derivative=derivative grid=grid).
plot_points
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| xs | any | required | Input list or collection, as required by this operation |
| ys | any | required | Y-coordinate list paired with xs |
| path | any | None | Path relative to the granted filesystem root |
| grid | any | None | Whether to draw a coordinate grid |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Plot paired x/y lists and return SVG text; unequal coordinate lengths are rejected |
Use xs, ys, path=None, grid=None as the inputs for this operation.
Effects: output.write.
Plot paired x/y lists and return SVG text; unequal coordinate lengths are rejected.
Return [Plot paired x/y lists and return SVG text; unequal coordinate lengths are rejected](> host_plot_points xs=xs ys=ys path=path grid=grid).
plot_conic
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| kind | any | required | Conic type accepted by plot_conic |
| a | any | required | First operand; its domain is described by this operation |
| b | any | None | Second operand; its domain is described by this operation |
| h | any | None | Horizontal shift of the conic center |
| k | any | None | Vertical shift of the conic center |
| path | any | None | Path relative to the granted filesystem root |
| grid | any | None | Whether to draw a coordinate grid |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Draw the selected conic with its dimensions and center offsets and return SVG text |
Use kind, a, b=None, h=None, k=None, path=None, grid=None as the inputs for this operation.
Effects: output.write.
Draw the selected conic with its dimensions and center offsets and return SVG text.
Return [Draw the selected conic with its dimensions and center offsets and return SVG text](> host_plot_conic kind=kind a=a b=b h=h k=k path=path grid=grid).