mathy_core: parse and manipulate math expressions

Mathy core is a python package (with type annotations) for working with math problems. It has a tokenizer for converting plain text into tokens, a parser for converting tokens into expression trees, a rule-based system for manipulating the trees, a layout system for visualizing trees, and a set of problem generation functions that can be used to generate datasets for ML training.

🚀 Quickstart

You can install mathy_core from pip:

pip install mathy_core

📖 Documentation

Check out https://core.mathy.ai for API documentation, examples, and more!

Examples

Consider a few examples to get a feel for what Mathy core does.

Evaluate an expression

Arithmetic is a snap.

from mathy_core import ExpressionParser

expression = ExpressionParser().parse("4 + 2")
assert expression.evaluate() == 6

Evaluate with variables

Variable values can be specified when evaluating an expression.

from mathy_core import ExpressionParser, MathExpression

expression: MathExpression = ExpressionParser().parse("4x + 2y")
assert expression.evaluate({"x": 2, "y": 5}) == 18

Transform an expression

Expressions can be changed using rules based on the properties of numbers.

from mathy_core import ExpressionParser
from mathy_core.rules import DistributiveFactorOutRule

input = "4x + 2x"
output = "(4 + 2) * x"
parser = ExpressionParser()

input_exp = parser.parse(input)
output_exp = parser.parse(output)

# Verify that the rule transforms the tree as expected
change = DistributiveFactorOutRule().apply_to(input_exp)
assert str(change.result) == output

# Verify that both trees evaluate to the same value
ctx = {"x": 3}
assert input_exp.evaluate(ctx) == output_exp.evaluate(ctx)

Development

Install the prerequisites in a virtual environment (python3 required)

sh tools/setup.sh

Run the test suite and view code-coverage statistics

sh tools/test.sh

The tests cover ~90% of the code so they're a good reference for how to use the various APIs.

Semantic Versioning

Before Mathy Core reaches v1.0 the project is not guaranteed to have a consistent API, which means that types and classes may move around or be removed. That said, we try to be predictable when it comes to breaking changes, so the project uses semantic versioning to help users avoid breakage.

Specifically, new releases increase the patch semver component for new features and fixes, and the minor component when there are breaking changes. If you don't know much about semver strings, they're usually formatted {major}.{minor}.{patch} so increasing the patch component means incrementing the last number.

Consider a few examples:

If you are concerned about breaking changes, you can pin the version in your requirements so that it does not go beyond the current semver minor component, for example if the current version was 0.1.37:

mathy_core>=0.1.37,<0.2.0

Contributors

Mathy Core wouldn't be possible without the wonderful contributions of the following people:

Justin DuJardin

JT Stukes

This project follows the all-contributors specification. Contributions of any kind welcome!