Base Classes#

class efficalc.Assumption(assumption: str)#

This is meant to clearly declare important assumptions which form the basis of your calculation template.

Parameters:

assumption (str) – The text describing your assumption

>>> a = Assumption("The seismic provisions of ASCE 7-16 control design")
Calculation report will show --> [ASSUME] The seismic provisions of ASCE 7-16 control design
class efficalc.Calculation(variable_name: str, expression: Operation | Expression | Variable | float | int, unit: str = None, description: str = None, reference: str = None, result_check: bool = False)#

This is the primary object used to define a calculation expression or calculated variable.

Parameters:

  • variable_name (str) – The symbolic name for the result of this calculation (LaTex formatted)

  • expression (a variable expression [i.e. a+b] or a constant number) – The calculation expression

  • unit (str, optional) – The physical units of the resulting variable (LaTex formatted), defaults to None

  • description (str, optional) – A text description for the calculation, defaults to None

  • reference (str, optional) – A short reference (e.g. code reference) to accompany the calculation, defaults to None

  • result_check (bool, optional) – This is used to indicate any Calculation that should be checked as a final result of your calculation template. When set to True, this Calculation will be displayed in the “Results” section of your design portal in the cloud version of efficalc, defaults to False

>>> a = Input("a",1,'ft')
>>> b = Input('b',4,'ft')
>>> c = Calculation('c', a + b, 'ft')
Calculation report will show --> c = a + b = 1ft + 4ft = 5ft
estimate_display_length() → CalculationLength#

Returns the estimated length of the LaTex formatted operation based on its symbolic and substituted representations.

Returns:

The estimated length of the Calculation

Return type:

CalculationLength

>>> a = Input('a',2,'ft')
>>> b = Input('b',3,'ft')
>>> c = Calculation('c', a + b, 'ft')
>>> c.estimate_display_length()
CalculationLength.SHORT
get_value()#

Alias for Calculation.result()

result() → float#

Returns the calculated result of the expression. If there is a ValueError or ZeroDivisionError, this will return 0 and set an error message in self.error.

Returns:

The result of the evaluated expression

Return type:

float

>>> a = Input('a',2,'ft')
>>> b = Input('b',3,'ft')
>>> c = Calculation('c', a + b, 'ft')
>>> print(c.get_value())
5
str_result_with_description() → str#

Returns a LaTex formatted string representation of the operation in the form “description; name = symbolicExpr”

str_substituted() → str#

Returns LaTex formatted representation of the operation with values substituted in for variables.

str_symbolic() → str#

Returns LaTex formatted symbolic representation of the operation using the variable names.

class efficalc.Comparison(a: Variable | Operation | Expression | float | int, comparator: Literal['<', '<=', '=', '!=', '==', '>', '>='], b: Variable | Operation | Expression | float | int, true_message: str = 'OK', false_message: str = 'ERROR', description: str = None, reference: str = None, result_check: bool = True)#

This is an object used to compare variables or constants as an explicit check in the calculations. It will compare the value of self.a against the value of self.b using the specified comparator and didplay a message depending on whether the comparison is true or false.

Parameters:

  • a (Input, Calculation, or a number) – The first variable or number

  • comparator ('<', '<=', '=', '!=', '==', '>', or '>=') – The comparision symbol as a string

  • b (Input, Calculation, or a number) – The second variable or number

  • true_message (str, optional) – The message that should desplay if the Comparison result is true, defaults to “OK”

  • false_message (str, optional) – The message that should desplay if the Comparison result is false, defaults to “ERROR”

  • description (str, optional) – A text description for the comparison, defaults to None

  • reference (str, optional) – A short text reference (e.g. code reference) to accompany the comparison, defaults to None

  • result_check (bool, optional) – This is used to indicate any Comparison that should be checked as a final result of your calculation template. When set to True, this Comparison will be displayed in the “Results” section of your design portal in the cloud version of efficalc, defaults to True

>>> a = Input("a",1,'ft')
>>> b = Input('b',4,'ft')
>>> Comparison(a, '>', b)
Calculation report will show --> Check a > b
                                    1 ft > 4 ft
                                    --> ERROR
get_message() → str#

Returns the appropriate message for the result of the comparison (.true_message or .false_message). If there was an error in the comparison, this will return the error message.

Returns:

The message for the evaluated comparison reult

Return type:

str

>>> a = Input('a',1,'ft')
>>> b = Input('b',4,'ft')
>>> c = Comparison(a, ">", b, false_message="NO GOOD")
>>> print(c.get_message())
NO GOOD
get_value() → bool#

Alias for is_passing()

is_passing() → bool#

Returns the calculated value of the comparison (True or False).

Returns:

The result of the evaluated comparison

Return type:

bool

>>> a = Input('a',1,'ft')
>>> b = Input('b',4,'ft')
>>> c = Comparison(a, ">", b)
>>> print(c.is_passing())
False
result() → bool#

Alias for is_passing()

str_substituted() → str#

Returns LaTex formatted representation of the comparison with values substituted in for variables.

str_symbolic() → str#

Returns LaTex formatted representation of the comparison using variable names.

class efficalc.ComparisonStatement(a: Variable | Operation | Expression | float | int, comparator: Literal['<', '<=', '=', '!=', '==', '>', '>='], b: Variable | Operation | Expression | float | int, comparator2: Literal['<', '<=', '=', '!=', '==', '>', '>='] = None, c: Variable | Operation | Expression | float | int = None, description: str = None, reference: str = None)#

This is an object for declaring the result of a comparison. It does not evaluate the values given, but rather displays the comparision exactly as it is given. This can be used to annotate or embellish if/else logic in your calculation templates.

Parameters:

  • a (Input, Calculation, or a number) – The first variable or number

  • comparator ('<', '<=', '=', '!=', '==', '>', or '>=') – The comparision symbol as a string

  • b (Input, Calculation, or a number) – The second variable or number

  • comparator2 ('<', '<=', '=', '!=', '==', '>', or '>=', optional) – A second comparision symbol as a string, defaults to None

  • c (Input, Calculation, or a number, optional) – A third variable or number, defaults to None

  • description (str, optional) – A text description for the comparison, defaults to None

  • reference (str, optional) – A short text reference (or code reference) to accompany the comparison, defaults to None

>>> a = Input("a",1,'ft')
>>> b = Input('b',4,'ft')
>>> ComparisonStatement(a, ">", b, description="Requirement for passing")
Calculation report will show --> Requirement for passing:
                                    --> a > b
str_symbolic()#

Returns LaTex formatted representation of the comparison using variable names.

class efficalc.Heading(text: str, head_level: Literal[1, 2, 3, 4, 5, 6, 7, 8] = 1, numbered: bool = True)#

This object can be used to add headings/section titles to calculation reports. If numbered, the heading number will auto-increment. The text size will generally be larger for higher levels (i.e. 1) than lower levels (i.e. 6)

Parameters:

  • text (str) – The text for the heading or title

  • head_level (int, optional) – The level of the heading from 1 to 6. Each heading level in its corresponding position would display as 1.2.3.4.5.6. before the heading text, defaults to 1

  • numbered (bool, optional) – Whether the heading should be numbered or not, defaults to True

>>> Heading("Default First Heading", head_level=1)
>>> Heading("Second Level Heading", head_level=2)
>>> Heading("Another Second Level Heading", head_level=2)
>>> Heading("Heading Without Number", head_level=2, numbered=False)
Calculation report will show -->    1.  Default First Heading
                                    1.1.  Second Level Heading
                                    1.2.  Another Second Level Heading
                                    Heading Without Number
class efficalc.Input(variable_name: str, default_value: int | float | str = 0, unit: str = None, description: str = None, reference: str = None, input_type: Literal['number', 'text', 'select'] = 'number', select_options: list = None, min_value: int | float = None, max_value: int | float = None, num_step: int | float | str = 'any', plain_text_value: bool = False)#

This is the primary object used to define an input which can change from calculation to calculation. Inputs may be numbers, text, or select elements with multiple options.

Parameters:

  • variable_name (str) – The symbolic name for this input variable (LaTex formatted)

  • default_value (float, int, or str) – The default value for the input. This will be overridden when explicit calculation inputs are provided to the calculation runner or in the design portal on the cloud version of efficalc, defaults to 0

  • unit (str, optional) – The physical units of the input variable (LaTex formatted), defaults to None

  • description (str, optional) – A text description for the input variable, defaults to None

  • reference (str, optional) – A short text reference (e.g. code reference) to accompany the input, defaults to None

  • input_type ("number", "text", or "select", optional) – The type of html input element to use in the design portal on the cloud version of efficalc, defaults to “number”.

  • select_options (str[], float[], or int[], optional) – A list of options for a “select” input_type variable. This is only applicable when .input_type is “select”, defaults to None

  • min_value (float, int, or None, optional) – Set the minimum value a number input is allowed to be in the design portal on the cloud version of efficalc, defaults to None

  • max_value (float, int, or None, optional) – Set the maximum value a number input is allowed to be in the design portal on the cloud version of efficalc, or “any” if the input type is not a number in the design portal on the cloud version of efficalc, defaults to None

  • num_step (float, int, or None, optional) – Specifies the interval between legal numbers in a number input field in the design portal on the cloud version of efficalc; see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/step, defaults to “any”

  • plain_text_value (bool, optional) – Set to True if the input value should be displayed as plain text rather than formatted as LeTex math, defaults to False

>>> a = Input("a",1,'ft')
>>> b = Input("b",4,'ft')
>>> Calculation('c', a + b, 'ft')
Calculation report will show --> c = a + b = 1ft + 4ft = 5ft
get_value()#

Returns the value of the input. Note that this will return the overridden input value when one is provided to the calculation runner or in the design portal on the cloud version of efficalc. If no override is provided, this will return the default value.

Returns:

The current value of the input variable

Return type:

float, int, or str

>>> a = Input('a',1,'ft')
>>> print(a.get_value())
1
str_result_with_name()#

Returns a LaTex formatted string representation of the input name and value in the form “name = value unit”

class efficalc.Symbolic(variable_name: str, expression: Operation | Expression | Variable | float | int | str, description: str = None, reference: str = None, result_check: bool = False)#

This will disply a symbolic variable expression in the calculation report. A substituted expression with values will not be displayed, nor will the result of the expression. You can optionally evaluate the result to use as a number in pure python calculations.

Parameters:

  • variable_name (str) – The symbolic name for the result of this calculation (LaTex formatted)

  • expression (a variable expression [i.e. a+b] or a constant number) – The calculation expression

  • description (str, optional) – A text description for the calculation, defaults to None

  • reference (str, optional) – A short reference (e.g. code reference) to accompany the calculation, defaults to None

  • result_check (bool, optional) – This is used to indicate any Symbolic that should be listed with the final results of your calculation template. When set to True, this Symbolic will be displayed in the “Results” section of your design portal in the cloud version of efficalc, defaults to False

>>> a = Input("a",1,'ft')
>>> b = Input('b',4,'ft')
>>> c = Symbolic('c', a + b)
Calculation report will show --> c = a + b
estimate_display_length() → CalculationLength#

Returns the estimated length of the LaTex formatted operation based on its symbolic representation.

Returns:

The estimated length of the Symbolic

Return type:

CalculationLength

>>> a = Input('a',2,'ft')
>>> b = Input('b',3,'ft')
>>> c = Symbolic('c', a + b, 'ft')
>>> c.estimate_display_length()
CalculationLength.SHORT
get_value()#

Alias for Symbolic.result()

result() → float#

Returns the calculated result of the expression. If there is a ValueError or ZeroDivisionError, this will return 0 and set an error message in self.error.

Returns:

The result of the evaluated expression

Return type:

float

>>> a = Input('a',2,'ft')
>>> b = Input('b',3,'ft')
>>> c = Symbolic('c', a + b, 'ft')
>>> print(c.result())
5
str_result_with_description() → str#

Returns a LaTex formatted string representation of the operation in the form “description; name = symbolicExpr”

str_result_with_unit()#

Alias for Symbolic.__str__()

str_substituted() → str#

Alias for Symbolic.str_symbolic()

str_symbolic() → str#

Returns LaTex formatted symbolic representation of the operation using the variable names.

class efficalc.Table(data: List[List[Any]], headers: List[any] | None = None, title: str | None = None, striped: bool = False, full_width: bool = False, result_check: bool = False, numbered_rows: bool = False)#

An object to display a table of data.

Parameters:

  • data (List[List[Any]] (a 2d list where each inner list is a row in the table)) – The data in the table. If this is an input table, the data will act as default data to be overridden by the calculation runner.

  • headers (List[Any], optional) – The headers for the table, defaults to None

  • title (str, optional) – The table title, defaults to None

  • striped (bool, optional) – Whether the table should be striped, defaults to False

  • full_width (bool, optional) – Whether the table should be full width, defaults to False

  • result_check (bool, optional) – This is used to indicate any Table that should be checked as a final result of your calculation template. When set to True, this Table will be displayed in the “Results” section of your design portal in the cloud version of efficalc, defaults to False

  • numbered_rows (bool, optional) – Whether to add row numbers (starting at 1) to each row, defaults to False

class efficalc.InputTable(default_data: List[List[Any]], headers: List[any], title: str | None = None, striped: bool = False, full_width: bool = False, numbered_rows: bool = False)#

A table that can be used to accept dynamic input data with the calculation runner and cloud version of efficalc.

Parameters:

  • default_data (List[List[Any]]) – The default data for the table. This will be overridden when explicit calculation inputs are provided to the calculation runner or in the design portal on the cloud version of efficalc

  • headers (List[Any]) – The headers for the table. This will be used as the unique identifier for the input table

  • title (str, optional) – The table title, defaults to None

  • striped (bool, optional) – Whether the table should be striped, defaults to False

  • full_width (bool, optional) – Whether the table should be full width, defaults to True

  • numbered_rows (bool, optional) – Whether to add row numbers (starting at 1) to each row, defaults to False

class efficalc.TextBlock(text: str, reference: str = None)#

This displays a block of text in the calculation report.

Parameters:

  • text (str) – The text

  • reference (str, optional) – A short text reference (e.g. code reference) to accompany the text, defaults to None

class efficalc.Title(title: str)#

This can be used for the main title in the calculation report. It is larger and bolder than the Heading and does not have the option to be numbered.

Parameters:

title (str) – The title text