Version: v0.14.0

parse_math

Stable function · Expressions

Tier: stable · Kind: function · Topic: Expressions

JuliaTypeScriptPythonRustGo
parse_mathparseMathparse_mathparse_mathParseMath

Julia

parse_math(text::AbstractString, names, format::Symbol)
parse_math(text::AbstractString, names, format::Symbol)

Read one expression, or one equation, written as math under a set of declared names: LaTeX for :markdown (Lean Math.parseLatex), Typst math for :typst (Math.parseTypst). The inverse of print_math : parse_math(print_math(e, names, f), names, f) is e in canonical form.

text is what a document display holds, without its delimiters. Text whose top is = reads as an equation, an OrderedDict with lhs and rhs, as a display does (Source.eqSides); any other text reads as an expression (a number, a name or an operator node, decoded as parse_markdown decodes a document). names (any collection of strings) plays the part of the variables a component declares: it decides how a run of letters reads (in LaTeX, RT is the name RT when it is declared, the product of R and T when they are). No template is in scope.

Throws a ParseError whose code is "removed_op" when the math uses an operator removed from the format (esm-spec §4.2), and "parse_error" for any other text that is not math, and for one past a bound of the reader (nested too deeply, or holding a number beyond the binary64 range).

parse_math("y = 2 k", ["k", "y"], :typst)
# OrderedDict("lhs" => "y", "rhs" => OrderedDict("args" => Any[2, "k"], "op" => "*"))

Source

Example (edit)

doc = load_path(joinpath(FIXTURES, "decay.esm"))
model = doc.models["Decay"]

# Edits return a new Model; the original is left alone.
decayed = ModelVariable(
    UnknownVariable; default = 0.0, units = "mol",
    description = "Amount that has decayed"
)
edited = add_variable(model, "decayed", decayed)
# The new equation, read from Typst math under the names it uses.
eq = parse_math("(dif italic(\"decayed\"))/(dif t) = lambda N", ["decayed", "lambda", "N"], :typst)
edited = add_equation(edited, Equation(expression_from_json(eq["lhs"]), expression_from_json(eq["rhs"])))
@assert ode_states(model) == ["N"]
@assert ode_states(edited) == ["N", "decayed"]

doc.models["Decay"] = edited
@assert validate(doc).is_valid

json = to_json(doc)
@assert occursin("\"decayed\"", json)

path = joinpath(mktempdir(), "decay_edited.esm")
write_path(doc, path)
reloaded = load_path(path)
@assert sort(ode_states(reloaded.models["Decay"])) == ["N", "decayed"]

From docs/api/examples/julia/editing.jl

Example (expressions)

# Read Typst math (or LaTeX, with :markdown) under the names it uses; the
# result is the expression's JSON form, which `expression_from_json` types.
names = ["k", "x", "y"]
expr = expression_from_json(parse_math("k x + y", names, :typst))
built = OpExpr("+", [OpExpr("*", [VarExpr("k"), VarExpr("x")]), VarExpr("y")])
@assert canonical_json(expr) == canonical_json(built)
# An expression shows as its Typst math.
@assert string(expr) == "k x + y"

@assert free_variables(expr) == Set(["k", "x", "y"])

# `substitute` takes a Dict{String,ASTExpr}: give the value type explicitly.
two_x = expression_from_json(parse_math("2 x", names, :typst))
replaced = substitute(expr, Dict{String, ASTExpr}("y" => two_x))
@assert string(replaced) == "k x + 2 x"
@assert free_variables(replaced) == Set(["k", "x"])

# Constant subexpressions fold away.
folded = simplify(expression_from_json(parse_math("x (1 + 1)", names, :typst)))
@assert string(folded) == "x dot 2"

# Text whose top is `=` reads as an equation, `lhs` and `rhs`.
eq = parse_math("(dif x)/(dif t) = -k x", names, :typst)
@assert string(expression_from_json(eq["rhs"])) == "-k x"

From docs/api/examples/julia/expressions.jl

TypeScript

function parseMath(text: string, names: readonly string[], format: DocumentFormat, options?: ParseDocumentOptions): unknown

Read one expression, or one equation, written as math under a set of declared names: LaTeX for 'markdown' (Math.parseLatex), Typst math for 'typst' (Math.parseTypst). The inverse of printMath : parseMath(printMath(e, names, f), names, f) is e in canonical form.

text is what a document display holds, without its delimiters. Text whose top is = reads as an equation, an object with lhs and rhs, as a display does (Source.eqSides); any other text reads as an expression. names plays the part of the variables a component declares: it decides how a run of letters reads (in LaTeX, RT is the name RT when it is declared, the product of R and T when they are). No template is in scope. Numbers come back as the document readers give them (see ParseDocumentOptions ).

Throws

  • EsmDiagnosticError — with code removed_op when the math uses an operator removed from the format (esm-spec §4.2), and parse_error for any other text that is not math, and for one past a bound of the reader (limits.ts): nested too deeply, or holding a number beyond the binary64 range.

Source

Example (edit)

const doc = loadPath(fixture('decay.esm'))
const model = doc.models!.Decay
assert.ok(!('ref' in model)) // narrows away an unresolved `{ ref }` mount

// Edits never mutate: each returns a new model.
const withVar = addVariable(model, 'fraction', {
  type: 'unknown',
  units: '1',
  description: 'Fraction of the initial amount remaining',
})
// The new equation, read from Typst math under the names it uses.
const fraction = parseMath('fraction = N/100', ['fraction', 'N'], 'typst') as Equation
const edited = addEquation(withVar, fraction)
assert.equal(model.equations.length, 2)
assert.equal(edited.equations.length, 3)
assert.deepEqual(observedUnknowns(edited), ['fraction', 'half_life'])

const newDoc = { ...doc, models: { ...doc.models, Decay: edited } }

// `toJson` returns the text; `writePath` writes it and returns nothing.
const json = toJson(newDoc)
const reloaded = loadString(json).models!.Decay
assert.match(json, /"fraction"/)

const outPath = join(outDir, 'decay_edited.esm')
writePath(newDoc, outPath)
assert.equal(readFileSync(outPath, 'utf8'), json)

From docs/api/examples/typescript/edit.ts

Example (expressions)

// Expressions are plain JSON trees; build one directly ...
const built: Expr = { op: '*', args: ['k', { op: '-', args: ['T_wall', 'T_air'] }] }

// ... or read one from LaTeX ('markdown') or Typst math, under the names it
// uses: the inverse of `printMath`.
const names = ['k', 'T_wall', 'T_air']
const latex = 'k \\left(T_{\\mathrm{wall}} - T_{\\mathrm{air}}\\right)'
const parsed = parseMath(latex, names, 'markdown') as Expr
assert.deepEqual(parsed, built)
assert.equal(printMath(parsed, names, 'markdown'), latex)
assert.deepEqual([...freeVariables(parsed)].sort(), ['T_air', 'T_wall', 'k'])
assert.equal(contains(parsed, 'T_wall'), true)

// Substitution is single-pass and returns a new tree.
const bound = substitute(parsed, { T_wall: 300, k: 0.05 })
assert.deepEqual(bound, { op: '*', args: [0.05, { op: '-', args: [300, 'T_air'] }] })
assert.deepEqual([...freeVariables(bound)], ['T_air'])
assert.equal(simplify(substitute(parsed, { T_wall: 300, T_air: 300 })), 0)

// Text whose top is `=` reads as an equation.
const eq = parseMath('(dif T_(upright("air")))/(dif t) = k (T_(upright("wall")) - T_(upright("air")))', names, 'typst') as {
  lhs: Expr
  rhs: Expr
}
assert.deepEqual(eq.rhs, built)

// Text that is not math raises a diagnostic error.
assert.throws(() => parseMath('k \\left(T_{\\mathrm{wall}}', names, 'markdown'), EsmDiagnosticError)

From docs/api/examples/typescript/expressions.ts

Python

parse_math(text: str, names: Iterable[str], format: DocumentFormat | str) -> Any

Read one expression, or one equation, written as math under a set of declared names: LaTeX for "markdown" (Math.parseLatex), Typst math for "typst" (Math.parseTypst). The inverse of print_math : parse_math(print_math(e, names, f), names, f) is e in canonical form.

text is what a document display holds, without its delimiters. Text whose top is = reads as an equation, a dict with lhs and rhs, as a display does (Source.eqSides); any other text reads as an expression (a number, a name or an operator node, in canonical form). names plays the part of the variables a component declares: it decides how a run of letters reads (in LaTeX, RT is the name RT when it is declared, the product of R and T when they are). No template is in scope.

Raises ParseError whose code is removed_op when the math uses an operator removed from the format (spec §4.2), and parse_error for any other text that is not math, and for one past a bound of the reader (.limits): nested too deeply, or holding a number beyond the binary64 range.

Source

Example (parse_math)

# Math reads into the JSON form of an expression, under the names it uses:
# LaTeX with "markdown", Typst math with "typst". It is the inverse of print_math.
names = ["k", "T_wall", "T_air"]
latex = r"k \left(T_{\mathrm{wall}} - T_{\mathrm{air}}\right)"
read = earthsci_ast.parse_math(latex, names, "markdown")
assert read == {"op": "*", "args": ["k", {"op": "-", "args": ["T_wall", "T_air"]}]}
assert earthsci_ast.print_math(read, names, "markdown") == latex
print(earthsci_ast.print_math(read, names, "typst"))

# Text whose top is `=` reads as an equation.
eq = earthsci_ast.parse_math("(dif x)/(dif t) = -k x", ["x", "k"], "typst")
assert eq == {
    "lhs": {"op": "D", "args": ["x"], "wrt": "t"},
    "rhs": {"op": "-", "args": [{"op": "*", "args": ["k", "x"]}]},
}

From docs/api/examples/python/expressions.py

Example (parse_math_error)

try:
    earthsci_ast.parse_math(r"k \left(T - ", ["k", "T"], "markdown")
except ParseError as exc:
    print("parse error:", exc)
    assert exc.code == "parse_error"
else:
    raise AssertionError("an unbalanced parenthesis should not parse")

From docs/api/examples/python/expressions.py

Rust

pub fn parse_math(text: &str, names: &[String], format: DocumentFormat) -> Result<Value, MathError>

Read one expression, or one equation, written as math under a set of declared names: LaTeX for DocumentFormat::Markdown (Math.parseLatex), Typst math for DocumentFormat::Typst (Math.parseTypst). The inverse of print_math : parse_math(&print_math(e, names, f), names, f) is e in canonical form.

text is what a document display holds, without its delimiters. Text whose top is = reads as an equation, an object with lhs and rhs, as a display does (Source.eqSides); any other text reads as an expression. names plays the part of the variables a component declares: it decides how a run of letters reads (in LaTeX, RT is the name RT when it is declared, the product of R and T when they are). No template is in scope.

Errors

A MathError with code removed_op when the math uses an operator removed from the format (spec §4.2), and parse_error for any other text that is not math, with where in the text reading went wrong, and for one past a bound of the Rust reader (limits): nested too deeply, or holding a number beyond the binary64 range.

Source · Rust docs

Example (edit)

let mut doc = load_path(fixture("decay.esm"))?;
let model = &doc.models.as_ref().unwrap()["Decay"];

// Track the decay product M. Edits return a new model; the input is
// left unchanged.
let product = ModelVariable {
    var_type: VariableType::Unknown,
    units: Some("mol".to_string()),
    default: Some(0.0.into()),
    description: Some("Amount produced".to_string()),
    default_units: None,
    element_type: None,
    shape: None,
    location: None,
    distribution: None,
    update: None,
    lb: None,
    ub: None,
};
let model = add_variable(model, "M", product)?;
// The new equation, read from Typst math under the names it uses.
let names = ["M", "N", "lambda"].map(String::from);
let eq = parse_math("(dif M)/(dif t) = lambda N", &names, DocumentFormat::Typst)?;
let model = add_equation(&model, serde_json::from_value::<Equation>(eq)?)?;
assert_eq!(model.variables.len(), 4);
assert_eq!(model.equations.len(), 3);

// Adding a name that is already declared is an error.
assert!(add_variable(&model, "N", model.variables["N"].clone()).is_err());

doc.models.as_mut().unwrap().insert("Decay".to_string(), model);

let json = to_json(&doc)?;
assert!(json.contains("\"M\""));

let out = std::env::temp_dir().join("decay_with_product.esm");
write_path(&doc, &out)?;
let reread = load_string(&std::fs::read_to_string(&out)?)?;
assert_eq!(reread.models.as_ref().unwrap()["Decay"].variables.len(), 4);

From docs/api/examples/rust/edit.rs

Example (expressions)

// Read Typst math (or LaTeX, with DocumentFormat::Markdown) under the
// names it uses: the inverse of print_math.
let names = ["k".to_string(), "A".to_string(), "x".to_string()];
let value = parse_math("k A - x", &names, DocumentFormat::Typst)?;
let rate: Expr = serde_json::from_value(value)?;
assert_eq!(rate.to_string(), "k A - x");

// Text whose top is `=` reads as an equation.
let value = parse_math("(dif x)/(dif t) = k A - x", &names, DocumentFormat::Typst)?;
let eq: Equation = serde_json::from_value(value)?;
assert_eq!(eq.lhs.to_string(), "(dif x)/(dif t)");

let mut free: Vec<String> = free_variables(&rate).into_iter().collect();
free.sort();
assert_eq!(free, ["A", "k", "x"]);

// Replace `k` with `2 j`.
let subs = HashMap::from([("k".to_string(), read("2 j", &["j"]))]);
let replaced = substitute(&rate, &subs);
assert_eq!(replaced.to_string(), "(2 j) A - x");

// Expressions are also plain Rust values.
let one = Expr::Variable("x".to_string());
assert_eq!(one.to_string(), "x");

From docs/api/examples/rust/expressions.rs

Go

func ParseMath(text string, names []string, format DocumentFormat) (any, error)

ParseMath reads one expression, or one equation, written as math under a set of declared names: LaTeX for DocumentMarkdown (Lean Math.parseLatex), Typst math for DocumentTypst (Math.parseTypst). It is the inverse of PrintMath: ParseMath(PrintMath(e, names, f), names, f) is e in canonical form (CanonicalizeDocument), the value PrintMath takes.

text is what a document display holds, without its delimiters. Text whose top is = reads as an equation, a map with lhs and rhs, as a display does (Source.eqSides); any other text reads as an expression. names plays the part of the variables a component declares: it decides how a run of letters reads (in LaTeX, RT is the name RT when it is declared, the product of R and T when they are). No template is in scope.

A text that is not math returns a *DocumentFormatError with code removed_op when it uses an operator removed from the format (esm-spec §4.2), and parse_error for any other text, and for one past a bound of the reader, as ParseMarkdown: nested too deeply, or holding a number beyond the binary64 range.

Source · Go docs

Example (edit)

doc, err := esm.LoadPath(fixture("decay.esm"))
if err != nil {
	log.Fatal(err)
}

units, desc := "mol", "Amount decayed so far"
model := esm.AddVariable(doc.Models["Decay"], "decayed", esm.ModelVariable{
	Type: "unknown", Units: &units, Description: &desc,
})
// Typst math under the names it uses; an `=` at the top makes it an
// equation, a map with `lhs` and `rhs`.
read, err := esm.ParseMath("decayed = 100 - N", []string{"decayed", "N"}, esm.DocumentTypst)
if err != nil {
	log.Fatal(err)
}
sides := read.(map[string]any)
model = esm.AddEquation(model, esm.Equation{LHS: sides["lhs"], RHS: sides["rhs"]})
doc.Models["Decay"] = model
fmt.Println(len(model.Equations), esm.Validate(doc).IsValid)

text, err := esm.ToJSON(doc)
if err != nil {
	log.Fatal(err)
}
fmt.Println(strings.Contains(text, `"decayed"`))

path := filepath.Join(dir, "decay-edited.esm")
if err := esm.WritePath(doc, path); err != nil {
	log.Fatal(err)
}
reread, err := esm.LoadPath(path)
if err != nil {
	log.Fatal(err)
}
fmt.Println(sortedKeys(reread.Models["Decay"].Variables))

From docs/api/examples/go/edit_test.go

Example (expressions)

read, err := esm.ParseMath(`k \left(T_{\mathrm{wall}} - T_{\mathrm{air}}\right)`,
	[]string{"k", "T_wall", "T_air"}, esm.DocumentMarkdown)
if err != nil {
	log.Fatal(err)
}
// ParseMath returns the decoded JSON tree; UnmarshalExpression makes it
// this package's Expression.
blob, err := json.Marshal(read)
if err != nil {
	log.Fatal(err)
}
parsed, err := esm.UnmarshalExpression(blob)
if err != nil {
	log.Fatal(err)
}
fmt.Println(sortedKeys(esm.FreeVariables(parsed)))

// The same tree, built directly: an operator node is an ExprNode, a
// variable is a string and a number is a float64.
built := esm.ExprNode{Op: "*", Args: []any{
	"k",
	esm.ExprNode{Op: "-", Args: []any{"T_wall", "T_air"}},
}}
fmt.Println(reflect.DeepEqual(built, parsed))

substituted, err := esm.Substitute(parsed, map[string]esm.Expression{
	"T_wall": 290.0,
	"k":      esm.ExprNode{Op: "/", Args: []any{1.0, "tau"}},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(esm.PrintMath(substituted, esm.ExpressionNames(substituted), esm.DocumentTypst))
fmt.Println(sortedKeys(esm.FreeVariables(substituted)))

value, err := esm.Evaluate(substituted, map[string]float64{"tau": 20, "T_air": 280})
if err != nil {
	log.Fatal(err)
}
fmt.Println(value)

From docs/api/examples/go/expressions_test.go