org.matheclipse.core.eval

Class EvalEngine

java.lang.Object

org.matheclipse.core.eval.EvalEngine

All Implemented Interfaces:

java.io.Serializable, IEvaluationEngine

public class EvalEngine
extends java.lang.Object
implements java.io.Serializable, IEvaluationEngine

The main evaluation algorithms for the .Symja computer algebra system

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DEBUG
static int	DOUBLE_PRECISION Use Num objects for numeric calculations up to 15 digits precision.
protected IExpr	fAnswer Contains the last result ("answer") expression of this evaluation engine or null if no answer is stored in the evaluation engine.
protected int	fIterationLimit
protected java.util.Set<ISymbol>	fModifiedVariablesList
protected LastCalculationsHistory	fOutList The history list for the Out[] function.
protected boolean	fPackageMode
protected int	fRecursionLimit

Constructor Summary

Constructors

Constructor and Description
EvalEngine()
EvalEngine(boolean relaxedSyntax) Constructor for an evaluation engine
EvalEngine(boolean relaxedSyntax, boolean outListDisabled) Constructor for an evaluation engine
EvalEngine(java.lang.String sessionID, int recursionLimit, int iterationLimit, java.io.PrintStream out, boolean relaxedSyntax, boolean outListDisabled) Constructor for an evaluation engine
EvalEngine(java.lang.String sessionID, int recursionLimit, java.io.PrintStream out, boolean relaxedSyntax, boolean outListDisabled) Constructor for an evaluation engine
EvalEngine(java.lang.String sessionID, java.io.PrintStream out)

Method Summary

Modifier and Type	Method and Description
boolean	addModifiedVariable(ISymbol arg0) For every evaluation store the list of modified variables in an internal list.
void	addOut(IExpr arg0) Add an expression to the Out[] list.
void	addRules(IAST ruleList)
IExpr	evalAST(IAST ast) Evaluate an AST.
IExpr	evalAttributes(ISymbol symbol, IAST ast) Evaluate an AST according to the attributes set in the header symbol.
IExpr	evalBlock(IExpr expr, IAST localVariablesList) Evaluate an expression for the given "local variables list".
IAST	evalFlatOrderlessAttributesRecursive(IAST ast) Evaluate the Flat and Orderless attributes of the given ast recursively.
IExpr	evalLoop(IExpr expr) Evaluate an object, if evaluation is not possible return F.NIL.
IExpr	evalN(IExpr expr)
IExpr	evalPattern(IExpr expr) Store the current numeric mode and evaluate the expression expr.
IPatternMatcher	evalPatternMatcher(IExpr expr) Store the current numeric mode and evaluate the expression expr.
IExpr	evalQuiet(IExpr expr) Evaluate an expression in "quiet mode".
IExpr	evalQuietNull(IExpr expr) Evaluate an expression in "quiet mode".
IExpr	evalRules(ISymbol symbol, IAST ast) Evaluate the rules for an AST.
IExpr	evalSetAttributes(IAST ast) Evaluate the ast recursively, according to the attributes Flat, HoldAll, HoldFirst, HoldRest, Orderless to create pattern-matching expressions directly or for the left-hand-side of a Set[], SetDelayed[], UpSet[] or UpSetDelayed[] expression
IExpr	evalSetAttributes(IAST ast, boolean noEvaluation) Evaluate the ast recursively, according to the attributes Flat, HoldAll, HoldFirst, HoldRest, Orderless to create pattern-matching expressions directly or for the left-hand-side of a Set[], SetDelayed[], UpSet[] or UpSetDelayed[] expression
IAST	evalTrace(IExpr expr, java.util.function.Predicate<IExpr> matcher, IAST list) Evaluate the expression and return the Trace[expr] (i.e. all (sub-)expressions needed to calculate the result).
boolean	evalTrue(IExpr expr) Test if expr could be evaluated to True.
IExpr	evaluate(IExpr expr) Store the current numeric mode and evaluate the expression expr.
IExpr	evaluate(java.lang.String expression) Parse the given expression String into an IExpr and evaluate it.
IExpr	evaluateNull(IExpr expr) Evaluate an object and reset the numeric mode to the value before the evaluation step.
IExpr	evalWithoutNumericReset(IExpr expr) Evaluate an object without resetting the numeric mode after the evaluation step.
static EvalEngine	get() Get the thread local evaluation engine instance
IExpr	getAnswer() Get the last result ("answer") expression of this evaluation engine.
IAssumptions	getAssumptions() Get the currently available assumptions if possible.
Context	getContext()
ContextPath	getContextPath()
int	getIterationLimit()
java.util.Map<ISymbol,java.util.List<IExpr>>	getLocalVariableStackMap()
java.util.Set<ISymbol>	getModifiedVariables() Get the list of modified variables
static int	getNextAnonymousCounter()
static java.lang.String	getNextCounter()
int	getNumericPrecision()
LastCalculationsHistory	getOutList()
java.io.PrintStream	getOutPrintStream()
IAST	getReapList()
int	getRecursionCounter()
int	getRecursionLimit()
java.lang.String	getSessionID()
IEvalStepListener	getStepListener() Get the defined step listener or null if no listener is assigned.
ISymbol	getUserVariable(java.lang.String symbolName) Returns the ISymbol variable created in this thread to which the specified symbolName is mapped, or null if this map contains no mapping for the symbolName.
int	incModuleCounter() Increment the module counter by 1 and return the result.
void	init() Resets internal flags and states:
boolean	isApfloat() Check if the ApfloatNum number type should be used instead of the Num type and the ApcomplexxNum number type should be used instead of the ComplexNum type for numeric evaluations.
static boolean	isApfloat(int precision) Check if the ApfloatNum number type should be used instead of the Num type and the ApcomplexxNum number type should be used instead of the ComplexNum type for numeric evaluations.
boolean	isEvalLHSMode() The engine evaluates the left-hand-side of a Set, SetDelayed,...
boolean	isNumericMode()
boolean	isOutListDisabled() Check if the appending of expressions to the history list for the Out[] function is enabled.
boolean	isPackageMode()
boolean	isQuietMode() If true the engine evaluates in "quiet" mode (i.e.
boolean	isRelaxedSyntax()
boolean	isStopRequested()
boolean	isTraceMode() If the trace mode is set the system writes an evaluation trace list or if additionally the stop after evaluation mode is set returns the first evaluated result.
static java.util.List<IExpr>	localStack(ISymbol symbol) Get the local variable stack for a given symbol name.
static java.util.List<IExpr>	localStackCreate(ISymbol symbol) Get the local variable stack for a given symbol name.
IExpr	parse(java.lang.String expression) Parse the given expression String into an IExpr without evaluation.
void	printMessage(java.lang.String str) Print a message to the Out stream, if the engine is not in "quiet mode".
ISymbol	putUserVariable(java.lang.String symbolName, ISymbol symbol) Associates the symbolName key with the ISymbol value.
static void	remove() Removes the current thread's value for the EvalEngine's thread-local variable.
void	removeUserVariables(java.util.Map<ISymbol,ISymbol> moduleVariables) Remove all moduleVariables from this evaluation engine.
void	reset() Reset the numeric mode flag and the recursion counter
static void	set(EvalEngine engine) Set the thread local evaluation engine instance
void	setAssumptions(IAssumptions assumptions) Set the assumptions for this evaluation engine
void	setContextPath(ContextPath fContextPath)
void	setIterationLimit(int i)
void	setNumericMode(boolean b)
void	setNumericMode(boolean b, int precision)
void	setNumericPrecision(int precision)
void	setOutListDisabled(boolean outListDisabled, int historyCapacity)
void	setOutPrintStream(java.io.PrintStream outPrintStream)
void	setPackageMode(boolean packageMode)
void	setQuietMode(boolean quietMode) If true the engine evaluates in "quiet" mode (i.e.
void	setReapList(IAST reapList)
void	setRecursionLimit(int i)
void	setRelaxedSyntax(boolean fRelaxedSyntax)
void	setSessionID(java.lang.String string)
void	setStepListener(IEvalStepListener stepListener) Set the step listener for this evaluation engine.
void	setStopRequested(boolean stopRequested)
void	setTraceMode(boolean b)
int	sizeOut() The size of the Out[] list
void	stopRequest()
static IAST	threadASTListArgs(IAST ast)
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

fRecursionLimit

protected int fRecursionLimit

fIterationLimit

protected int fIterationLimit

fPackageMode

protected boolean fPackageMode

fModifiedVariablesList

protected java.util.Set<ISymbol> fModifiedVariablesList

fOutList

protected transient LastCalculationsHistory fOutList

The history list for the Out[] function.

See Also:

org.matheclipse.core.reflection.Out

fAnswer

protected transient IExpr fAnswer

Contains the last result ("answer") expression of this evaluation engine or null if no answer is stored in the evaluation engine.

DOUBLE_PRECISION

public static final int DOUBLE_PRECISION

Use Num objects for numeric calculations up to 15 digits precision.

See Also:

Constant Field Values

DEBUG

public static final boolean DEBUG

See Also:

Constant Field Values

Constructor Detail

EvalEngine

public EvalEngine()

EvalEngine

public EvalEngine(boolean relaxedSyntax)

Constructor for an evaluation engine

Parameters:

relaxedSyntax - if true, the parser doesn't distinguish between upper and lower case identifiers

EvalEngine

public EvalEngine(boolean relaxedSyntax,
                  boolean outListDisabled)

Constructor for an evaluation engine

Parameters:

relaxedSyntax - if true, the parser doesn't distinguidh between upper and lower case identifiers

outListDisabled - if true, no output history for the Out() function is stored in the evaluation engine.

EvalEngine

public EvalEngine(java.lang.String sessionID,
                  int recursionLimit,
                  int iterationLimit,
                  java.io.PrintStream out,
                  boolean relaxedSyntax,
                  boolean outListDisabled)

Constructor for an evaluation engine

Parameters:

sessionID - an ID which uniquely identifies this session

iterationLimit - the maximum allowed iteration limit (if set to zero, no limit will be checked)

recursionLimit - the maximum allowed recursion limit (if set to zero, no limit will be checked)

out - the output print stream

relaxedSyntax - if true, the parser doesn't distinguidh between upper and lower case identifiers

outListDisabled - if true, no output history for the Out() function is stored in the evaluation engine.

EvalEngine

public EvalEngine(java.lang.String sessionID,
                  int recursionLimit,
                  java.io.PrintStream out,
                  boolean relaxedSyntax,
                  boolean outListDisabled)

Constructor for an evaluation engine

Parameters:

sessionID - an ID which uniquely identifies this session

recursionLimit - the maximum allowed recursion limit (if set to zero, no limit will be checked)

out - the output print stream

relaxedSyntax - if true, the parser doesn't distinguidh between upper and lower case identifiers

outListDisabled - if true, no output history for the Out() function is stored in the evaluation engine.

EvalEngine

public EvalEngine(java.lang.String sessionID,
                  java.io.PrintStream out)

Method Detail

evalQuiet

public final IExpr evalQuiet(IExpr expr)

Evaluate an expression in "quiet mode". If evaluation is not possible return the input object. In "quiet mode" all warnings would be suppressed.

Parameters:

expr - the expression which should be evaluated

Returns:

the evaluated object

See Also:

evalWithoutNumericReset(IExpr)

evalQuietNull

public final IExpr evalQuietNull(IExpr expr)

Evaluate an expression in "quiet mode". If evaluation is not possible return F.NIL. In "quiet mode" all warnings would be suppressed.

Parameters:

expr - the expression which should be evaluated

Returns:

the evaluated object or F.NUIL if no evaluation was possible

See Also:

evalWithoutNumericReset(IExpr)

get

public static EvalEngine get()

Get the thread local evaluation engine instance

Returns:

getNextAnonymousCounter

public static int getNextAnonymousCounter()

getNextCounter

public static java.lang.String getNextCounter()

isApfloat

public static boolean isApfloat(int precision)

Check if the ApfloatNum number type should be used instead of the Num type and the ApcomplexxNum number type should be used instead of the ComplexNum type for numeric evaluations.

Parameters:

precision - the given precision

Returns:

true if the given precision is greater than EvalEngine.DOUBLE_PRECISION

See Also:

ApfloatNum, ApcomplexNum

localStack

public static final java.util.List<IExpr> localStack(ISymbol symbol)

Get the local variable stack for a given symbol name. If the local variable stack doesn't exist, return null

Parameters:

symbolName -

Returns:

null if the stack doesn't exist

localStackCreate

public static java.util.List<IExpr> localStackCreate(ISymbol symbol)

Get the local variable stack for a given symbol name. If the local variable stack doesn't exist, create a new one for the symbol.

Parameters:

symbolName -

Returns:

remove

public static void remove()

Removes the current thread's value for the EvalEngine's thread-local variable.

See Also:

ThreadLocal.remove()

set

public static void set(EvalEngine engine)

Set the thread local evaluation engine instance

threadASTListArgs

public static IAST threadASTListArgs(IAST ast)

addModifiedVariable

public boolean addModifiedVariable(ISymbol arg0)

For every evaluation store the list of modified variables in an internal list.

Parameters:

arg0 -

Returns:

addOut

public void addOut(IExpr arg0)

Add an expression to the Out[] list. To avoid memory leaks you can disable the appending of expressions to the output history.

See Also:

#setOutListDisabled(boolean)

addRules

public void addRules(IAST ruleList)

evalAST

public IExpr evalAST(IAST ast)

Evaluate an AST. The evaluation steps are controlled by the header attributes.

Parameters:

ast -

Returns:

F.NIL if no evaluation happened

evalAttributes

public IExpr evalAttributes(ISymbol symbol,
                            IAST ast)

Evaluate an AST according to the attributes set in the header symbol. The evaluation steps are controlled by the header attributes.

Parameters:

ast -

Returns:

evalBlock

public IExpr evalBlock(IExpr expr,
                       IAST localVariablesList)

Evaluate an expression for the given "local variables list". If evaluation is not possible return the input object.

Parameters:

expr - the expression which should be evaluated

localVariablesList - a list of symbols which should be used as local variables inside the block

Returns:

the evaluated object

evalFlatOrderlessAttributesRecursive

public IAST evalFlatOrderlessAttributesRecursive(IAST ast)

Evaluate the Flat and Orderless attributes of the given ast recursively.

Parameters:

ast -

Returns:

F.NIL if no evaluation was possible

evalLoop

public IExpr evalLoop(IExpr expr)

Evaluate an object, if evaluation is not possible return F.NIL.

Parameters:

expr - the expression which should be evaluated

Returns:

the evaluated expression or F.NIL if evaluation isn't possible

See Also:

evalWithoutNumericReset(IExpr)

evalPattern

public final IExpr evalPattern(IExpr expr)

Store the current numeric mode and evaluate the expression expr. After evaluation reset the numeric mode to the value stored before the evaluation starts. If evaluation is not possible return the input object.

Note: if this method catches exception org.matheclipse.parser.client.math.MathException, it returns the input expression.

Parameters:

expr - the object which should be evaluated

Returns:

the evaluated object

evalPatternMatcher

public final IPatternMatcher evalPatternMatcher(IExpr expr)

Store the current numeric mode and evaluate the expression expr. After evaluation reset the numeric mode to the value stored before the evaluation starts. If evaluation is not possible return the input object.

Parameters:

expr - the object which should be evaluated

Returns:

an IPatterMatcher cretaed from the given expression.

evalRules

public IExpr evalRules(ISymbol symbol,
                       IAST ast)

Evaluate the rules for an AST.

Parameters:

symbol -

ast -

Returns:

F.NIL if no evaluation happened

evalSetAttributes

public IExpr evalSetAttributes(IAST ast)

Evaluate the ast recursively, according to the attributes Flat, HoldAll, HoldFirst, HoldRest, Orderless to create pattern-matching expressions directly or for the left-hand-side of a Set[], SetDelayed[], UpSet[] or UpSetDelayed[] expression

Parameters:

ast -

Returns:

ast if no evaluation was executed.

evalSetAttributes

public IExpr evalSetAttributes(IAST ast,
                               boolean noEvaluation)

Evaluate the ast recursively, according to the attributes Flat, HoldAll, HoldFirst, HoldRest, Orderless to create pattern-matching expressions directly or for the left-hand-side of a Set[], SetDelayed[], UpSet[] or UpSetDelayed[] expression

Parameters:

ast -

noEvaluation - (sub-)expressions which contain no patterns should not be evaluated

Returns:

ast if no evaluation was executed.

evalTrace

public final IAST evalTrace(IExpr expr,
                            java.util.function.Predicate<IExpr> matcher,
                            IAST list)

Evaluate the expression and return the Trace[expr] (i.e. all (sub-)expressions needed to calculate the result).

Parameters:

expr - the expression which should be evaluated.

matcher - a filter which determines the expressions which should be traced, If the matcher is set to null, all expressions are traced.

list - an IAST object which will be cloned for containing the traced expressions. Typically a F.List() will be used.

Returns:

evalTrue

public final boolean evalTrue(IExpr expr)

Test if expr could be evaluated to True. If a org.matheclipse.parser.client.math.MathException occurs during evaluation, return False.

Parameters:

expr -

Returns:

true if the expression could be evaluated to symbol True and false in all other cases

evaluate

public final IExpr evaluate(IExpr expr)

Store the current numeric mode and evaluate the expression expr. After evaluation reset the numeric mode to the value stored before the evaluation starts. If evaluation is not possible return the input object.

Parameters:

expr - the object which should be evaluated

Returns:

the evaluated object

evalN

public final IExpr evalN(IExpr expr)

evaluate

public final IExpr evaluate(java.lang.String expression)

Parse the given expression String into an IExpr and evaluate it.

Parameters:

astString - an expression in math formula notation

Returns:

Throws:

SyntaxError - if a parsing error occurs

evaluateNull

public final IExpr evaluateNull(IExpr expr)

Evaluate an object and reset the numeric mode to the value before the evaluation step. If evaluation is not possible return F.NIL.

Parameters:

expr - the object which should be evaluated

Returns:

the evaluated object or F.NIL if no evaluation was possible

evalWithoutNumericReset

public final IExpr evalWithoutNumericReset(IExpr expr)

Evaluate an object without resetting the numeric mode after the evaluation step. If evaluation is not possible return the input object,

Specified by:

evalWithoutNumericReset in interface IEvaluationEngine

Parameters:

expr - the object which should be evaluated

Returns:

the evaluated object

getAnswer

public IExpr getAnswer()

Get the last result ("answer") expression of this evaluation engine.

Returns:

null if no answer is stored in the evaluation engine.

getAssumptions

public IAssumptions getAssumptions()

Get the currently available assumptions if possible.

Returns:

null if no assumptions are available

getContext

public Context getContext()

getContextPath

public ContextPath getContextPath()

getIterationLimit

public int getIterationLimit()

getLocalVariableStackMap

public final java.util.Map<ISymbol,java.util.List<IExpr>> getLocalVariableStackMap()

getModifiedVariables

public java.util.Set<ISymbol> getModifiedVariables()

Get the list of modified variables

Returns:

getNumericPrecision

public int getNumericPrecision()

getOutList

public LastCalculationsHistory getOutList()

getOutPrintStream

public java.io.PrintStream getOutPrintStream()

getReapList

public IAST getReapList()

Returns:

the reapList

getRecursionCounter

public int getRecursionCounter()

getRecursionLimit

public int getRecursionLimit()

Returns:

getSessionID

public java.lang.String getSessionID()

Returns:

getStepListener

public IEvalStepListener getStepListener()

Get the defined step listener or null if no listener is assigned.

Returns:

null if no step listener is assigned.

getUserVariable

public ISymbol getUserVariable(java.lang.String symbolName)

Returns the ISymbol variable created in this thread to which the specified symbolName is mapped, or null if this map contains no mapping for the symbolName.

Parameters:

name -

Returns:

incModuleCounter

public int incModuleCounter()

Increment the module counter by 1 and return the result.

Returns:

the module counter

init

public final void init()

Description copied from interface: IEvaluationEngine

Resets internal flags and states:

Specified by:

init in interface IEvaluationEngine

isApfloat

public boolean isApfloat()

Check if the ApfloatNum number type should be used instead of the Num type and the ApcomplexxNum number type should be used instead of the ComplexNum type for numeric evaluations.

Returns:

true if the required precision is greater than EvalEngine.DOUBLE_PRECISION

See Also:

ApfloatNum, ApcomplexNum

isEvalLHSMode

public boolean isEvalLHSMode()

The engine evaluates the left-hand-side of a Set, SetDelayed,... expression.

Returns:

isNumericMode

public boolean isNumericMode()

Returns:

true if the EvalEngine runs in numeric mode.

isOutListDisabled

public boolean isOutListDisabled()

Check if the appending of expressions to the history list for the Out[] function is enabled. If enabled, the special variable $ans returns the result from the last evluation done with this evaluation engine.

See Also:

org.matheclipse.core.reflection.Out

isPackageMode

public boolean isPackageMode()

isQuietMode

public boolean isQuietMode()

If true the engine evaluates in "quiet" mode (i.e. no warning messages are showw in the evaluation).

See Also:

Quiet

isRelaxedSyntax

public boolean isRelaxedSyntax()

Returns:

the fRelaxedSyntax

isStopRequested

public boolean isStopRequested()

Returns:

Returns the stopRequested.

isTraceMode

public boolean isTraceMode()

If the trace mode is set the system writes an evaluation trace list or if additionally the stop after evaluation mode is set returns the first evaluated result.

Returns:

See Also:

org.matheclipse.core.reflection.system.Trace

parse

public final IExpr parse(java.lang.String expression)

Parse the given expression String into an IExpr without evaluation.

Parameters:

astString - an expression in math formula notation

Returns:

Throws:

SyntaxError - if a parsing error occurs

printMessage

public void printMessage(java.lang.String str)

Print a message to the Out stream, if the engine is not in "quiet mode".

Parameters:

str - the message which should be printed

putUserVariable

public ISymbol putUserVariable(java.lang.String symbolName,
                               ISymbol symbol)

Associates the symbolName key with the ISymbol value.

Parameters:

symbolName -

symbol -

Returns:

removeUserVariables

public void removeUserVariables(java.util.Map<ISymbol,ISymbol> moduleVariables)

Remove all moduleVariables from this evaluation engine.

Parameters:

moduleVariables -

reset

public void reset()

Reset the numeric mode flag and the recursion counter

setAssumptions

public void setAssumptions(IAssumptions assumptions)

Set the assumptions for this evaluation engine

Parameters:

assumptions -

setContextPath

public void setContextPath(ContextPath fContextPath)

setIterationLimit

public void setIterationLimit(int i)

setNumericMode

public void setNumericMode(boolean b)

Parameters:

b -

setNumericMode

public void setNumericMode(boolean b,
                           int precision)

Parameters:

b -

setNumericPrecision

public void setNumericPrecision(int precision)

setOutListDisabled

public void setOutListDisabled(boolean outListDisabled,
                               int historyCapacity)

Parameters:

outListDisabled - if false create a LastCalculationsHistory(historyCapacity), otherwise no history of the last calculations will be saved and the Out() function (or % operator) will be unevaluated.

historyCapacity - the number of last entries of the calculations which should be stored.

setOutPrintStream

public void setOutPrintStream(java.io.PrintStream outPrintStream)

setPackageMode

public void setPackageMode(boolean packageMode)

setQuietMode

public void setQuietMode(boolean quietMode)

If true the engine evaluates in "quiet" mode (i.e. no warning messages are showw in the evaluation).

Parameters:

quietMode -

setReapList

public void setReapList(IAST reapList)

Parameters:

reapList - the reapList to set

setRecursionLimit

public void setRecursionLimit(int i)

Parameters:

i -

setRelaxedSyntax

public void setRelaxedSyntax(boolean fRelaxedSyntax)

Parameters:

fRelaxedSyntax - the fRelaxedSyntax to set

setSessionID

public void setSessionID(java.lang.String string)

Parameters:

string -

setStepListener

public void setStepListener(IEvalStepListener stepListener)

Set the step listener for this evaluation engine. The method also calls setTraceMode(true) to enable the trace mode. The caller is responsible for calling setTraceMode(false) if no further listening is desirable.

Parameters:

stepListener - the listener which should listen to the evaluation steps.

setStopRequested

public void setStopRequested(boolean stopRequested)

Parameters:

stopRequested - The stopRequested to set.

setTraceMode

public void setTraceMode(boolean b)

Parameters:

b -

sizeOut

public int sizeOut()

The size of the Out[] list

Returns:

stopRequest

public void stopRequest()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object