Getting Started

New to Leonardo? Lessons: in your program is the guided path through this page and everything after it — eleven short lessons, each with an exercise. If you would rather type at a prompt than write Scala, start at Lessons: at the prompt instead, which needs no installation at all.

Prerequisites

  • JDK 25 or later: every Leonardo module is compiled for Java 25
  • Scala 3.3 or later
  • sbt 1.9 or later

Adding Leonardo to your project

Leonardo is published to Maven Central for Scala 3.3 LTS, and ships as three artifacts. The library is what you almost always want:

libraryDependencies += "it.grypho" %% "leonardo" % "0.0.0+1-410c898c-SNAPSHOT"

The interactive REPL is a separate artifact, because it is the only part that needs JLine — a terminal library a library consumer would never call. Add it only if you want to embed or extend the REPL:

libraryDependencies += "it.grypho" %% "leonardo-repl" % "0.0.0+1-410c898c-SNAPSHOT"

leonardo-repl depends on leonardo, so the second line replaces the first rather than supplementing it.

The third, leonardo-mcp, is not a library to depend on: it is a server that lets an AI assistant call the REPL over the Model Context Protocol, run as a jar. See MCP server.

Import conventions

Leonardo is split across focused packages. Import what you need:

import it.grypho.scala.leonardo.core.*      // _Expression, _Value, _Number, _Variable, Environment
import it.grypho.scala.leonardo.scalar.*    // Sum, Product, Power, Sin, derive, simplify, …
import it.grypho.scala.leonardo.matrix.*    // _Matrix, MatSum, MatProduct, Transpose, Determinant, Inverse
import it.grypho.scala.leonardo.equation.*  // _Equation, solve, solveSystem
import it.grypho.scala.leonardo.parser.Parser
import it.grypho.scala.leonardo.cli.Session   // leonardo-repl artifact, not leonardo

The other domain packages follow the same pattern, each importing only core and scalar (and some one another): transform (Laplace, Fourier, z, dft), ode, logic, probability, statistics, domain, vector, control, optimize and latex. Import the one a task needs rather than all of them, and pick one call style: importing scalar.* beside scalar.Syntax.* makes every bare call such as derive(e, x) ambiguous, since the extension methods share the functions’ names. Architecture shows how the packages layer.

Parsing

The Parser converts a string into an expression tree:

Parser.parse("sin(x)^2 + cos(x)^2").get.toString
// res0: String = "((sin(x) ^ 2.0) + (cos(x) ^ 2.0))"

The result is immutable; the same tree object can be evaluated many times with different environments.

Parsing failures return a Failure result rather than throwing:

val bad = Parser.parse("sin(")
// bad: ParseResult[_Expression] = Failure(
//   msg = "'√' expected but end of source found",
//   next = CharSequenceReader()
// )
bad.successful
// res1: Boolean = false

Evaluating

An expression evaluates to either a concrete _Value (wrapped in Right) or a symbolic remainder (wrapped in Left):

val x    = _Variable("x")
val expr = Sum(Sin(x), Cos(x))

Without any binding, the expression stays symbolic:

expr.eval(new Environment())
// res2: Either[_Expression, _Value] = Left(
//   Sum(a = Sin(_Variable("x")), b = Cos(_Variable("x")))
// )

Bind x and the result folds to a number:

val env = new Environment(5, Map("x" -> _Number(0.0)))
// env: Environment = it.grypho.scala.leonardo.core.Environment@28095e8b
expr.eval(env)
// res3: Either[_Expression, _Value] = Right(_Number(1.0))

Precision

Environment carries a decimal precision used for display and rounding. The default is 5; override it per call:

val highPrecision = new Environment(10, Map("x" -> _Number(math.Pi / 4)))
// highPrecision: Environment = it.grypho.scala.leonardo.core.Environment@7e5cd421
expr.eval(highPrecision)
// res4: Either[_Expression, _Value] = Right(_Number(1.414213562373095))

Using the REPL

Launch with sbt repl from a clone of the repository (the alias for sbt "replModuleJVM/runMain it.grypho.scala.leonardo.cli.repl"; a bare runMain fails from the root aggregate). Programmatically, Session.execute is the pure testable core:

val s = Session()
s.execute("x := 1.5708")   // π/2 ≈ 1.5708
s.execute("sin(x) + cos(x)")
// res6: String = "1.0"

This site uses Just the Docs, a documentation theme for Jekyll.