SeExpr v3 FAQ

SeExpr v3 FAQ

What's new in SeExpr?

Variable Typing

Expression Evaluation

Variable Blocks

Miscellaneous

Which versions have these features?

What do I have to change in my code to use this version?

What is LLVM? Can I switch it off?

Why did we make these changes?

What are the performance impacts -- any testing metrics?

How do I write expression functions or plugins now?

What are some examples?

How do I use variable blocks?

How can I contribute to the code?

Where can I find some developer docs?

Design docs

Class docs

What's new in SeExpr?

Variable Typing

Statically typed variables and support for up to 16-dimensional vectors:

FP[1] for scalars, eg width, height

FP[3] for 3d vectors, eg point, normal, color

FP[4] eg quaternion

FP[16] eg 4x4 matrix

Lifetime modifiers of type:

For more details, see:

  • SeExpr Type System Overview
  • Type System for SeExpr: Lifetime Qualifier Overview
  • Expression Evaluation

    Faster expression evaluation using interpreter or using LLVM compiler

    The default is set to LLVM evaluation. To set explicitly:

    setenv SE_EXPR_EVAL LLVM
    setenv SE_EXPR_EVAL INTERPRETER

    While LLVM is faster to evaluate, there is more overhead during prep().

    See updated tutorials at http://wdas.github.io/SeExpr/doxygen/

    Variable Blocks

    Shared variable blocks for evaluating multiple expressions at once.

    Threading with variable blocks: each thread could have it's own variable block to operate on independently.

    More details on using variable blocks is documented at http://wdas.github.io/SeExpr/doxygen/varblocks.html

    Miscellaneous

    New recursive descent parser, only used for the Python AST Tools.

    Which versions have these features?

    Open source version 3.0 and above on https://github.com/wdas/SeExpr

    What do I have to change in my code to use this version?

    See Porting your code to SeExpr v3

    What is LLVM? Can I switch it off?

    From http://llvm.org/: "The LLVM Project is a collection of modular and reusable compiler and toolchain technologies." SeExpr uses LLVM under the hood for generating IR (intermediate representation) code from our expression language, to more efficiently evaluate the expressions. For more information, refer to http://llvm.org/docs/; for a useful tutorial example, see http://llvm.org/docs/tutorial/index.html.

    By default, expression evaluation will use LLVM if it's available; otherwise it will use our own internal interpreter. To switch off LLVM compilation and explicitly use the interpreter, set this environment variable:

    setenv SE_EXPR_EVAL INTERPRETER

    To switch LLVM on explicitly:

    setenv SE_EXPR_EVAL LLVM

    For default behavior:

    unsetenv SE_EXPR_EVAL

    Why did we make these changes?

    We use our expression language heavily in creating textures and particle effects, in everything from growing fur to growing vegetation. We have over 2,000 expressions in our shared library, in addition to innumerable other uses of expressions throughout our pipeline. And in most cases, each expression is re-computed many times across points on a surface or frames in an animation. If we can improve the performance of expression evaluation, it has the potential to ripple out to many areas of the production pipeline.

    More robust variable typing allows us to better identify expression errors during prep, which happens only once, rather than during evaluation, which repeats multiple times. This allows the expression author to more quickly resolve errors and iterate towards a correct solution faster.

    Using LLVM to compile expressions prior to evaluation significantly speeds up the evaluation. The overhead of code generation happens once during the prep process, while the performance improvements are reaped multiple times during evaluation for a noticeable overall speed improvement.

    What are the performance impacts -- any testing metrics?

    Overall, expression evaluation is faster, whether you enable LLVM evaluation or use the native SeExpr interpreter for evaluation.

    The following chart shows the percent decrease (or increase) in ms for evaluation of expressions in our our internal shared library, as compared to the previous version of SeExpr.

    The blue line shows evaluation time increase or decrease comparing v1 and v2 using the native interpreter. The red line shows the comparison between v1 and v2 using LLVM compilation. (Note: These are older metrics from April, and I'll be re-running for a more current view.)

    expr-performance-chart.jpg

    Because of the overhead involved in code generation, running a very simple example expression only once will actually be slower using LLVM. However, our typical use case involves many repetitions of the same expression across the points on a surface or frames in an animation.

    How do I write expression functions or plugins now?

    See How to Write an Expression Function and Plugin

    What are some examples?

    For subclassing an expression, see the CalculatorExpr class in asciiCalculator.cpp

    For writing a custom expression function, see the CurveFuncX class in ExprBuiltins.cpp

    How do I use variable blocks?

    See http://wdas.github.io/SeExpr/doxygen/varblocks.html

    How can I contribute to the code?

    Glad you asked! We've defined a list of github issues with the label "wishlist." These are issues we would love to have the community contribute solutions for. Guidelines for contributing will be published.

    Where can I find some developer docs?

    Design docs

    Class docs

    See our SeExpr Doxygen page.