Skip to content

check_result

checks.check_result

Result data structure for structural checks.

Classes:

  • CheckResult –

    Contains the results of an engineering check.

checks.check_result.CheckResult dataclass 

CheckResult(
    provided: float | None = None,
    required: float | None = None,
    operator: Literal["<", "<=", "==", ">=", ">", "!="] = "<=",
    unity_check: float | None = None,
    factor_of_safety: float | None = None,
    is_ok: bool | None = None,
)

Contains the results of an engineering check.

This class stores the outcome of any verification, providing both pass/fail status and detailed information about capacity utilization or factor of safety. Use this to understand whether your design meets code requirements and how efficiently you're using the available capacity.

Recommended initialization methods: - from_comparison(provided: float, required: float, operator: str = "<="): Create a CheckResult from direct provided and required values with a comparison operator. - from_unity_check(unity_check: float): Create a CheckResult from a unity check value (provided/required). - from_factor_of_safety(factor_of_safety: float): Create a CheckResult from a factor of safety value (required/provided). - from_bool(is_ok: bool): Create a CheckResult from a simple pass/fail boolean.

Initialization notes: - When only is_ok is provided: the other fields will remain None. - When unity_check is provided: factor_of_safety and is_ok will be inferred. - When factor_of_safety is provided: unity_check and is_ok will be inferred. - When both provided and required (with optional operator) are provided: unity_check, factor_of_safety, and is_ok will be calculated based on the operator. Special handling is applied for zero values and "==" or "!=" operators to avoid division by zero and ensure meaningful results.

Direct initialization: - Ensure that the combination of fields provided is consistent. For example: - CheckResult(is_ok=True, unity_check=0.8) is valid. - CheckResult(is_ok=False, unity_check=0.8) will raise a ValueError.

Parameters:

  • provided (float | None, default: None ) –

    The actual calculated value from the design (e.g., applied load, stress).

  • required (float | None, default: None ) –

    The allowable or required value for the design (e.g., capacity, code required).

  • operator (str, default: '<=' ) –

    The comparison operator used to evaluate the check: "<", "<=", "==", ">=", ">", or "!=". Default is "<=", meaning provided <= required.

  • unity_check (float | None, default: None ) –

    The ratio of provided to required (provided / required). Values <= 1.0 indicate passing checks.

  • factor_of_safety (float | None, default: None ) –

    The factor of safety (required / provided). Values >= 1.0 indicate passing checks.

  • is_ok (bool | None, default: None ) –

    Indicates whether the check passed (True) or failed (False). If None, it will be inferred from unity_check or factor_of_safety if available.

Notes
  • Always check is_ok to determine if design modifications are needed.
  • Use unity_check to optimize your design efficiency.
  • Use factor_of_safety to understand safety margins.
  • Values close to 1.0 indicate efficient but potentially risky designs.

checks.check_result.CheckResult.from_bool classmethod 

from_bool(is_ok: bool) -> Self

Create a CheckResult from a boolean pass/fail value only.

Parameters:

  • is_ok (bool) –

    Whether the check passed (True) or failed (False).

Example
  • CheckResult.from_bool(is_ok=True) -> CheckResult with is_ok=True, other fields None

Returns:

  • CheckResult –

    A new CheckResult instance with only is_ok set.

Source code in blueprints/checks/check_result.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
@classmethod
def from_bool(cls, is_ok: bool) -> Self:
    """
    Create a CheckResult from a boolean pass/fail value only.

    Parameters
    ----------
    is_ok : bool
        Whether the check passed (True) or failed (False).

    Example
    -------
    - CheckResult.from_bool(is_ok=True)
      -> CheckResult with is_ok=True, other fields None

    Returns
    -------
    CheckResult
        A new CheckResult instance with only is_ok set.
    """
    return cls(is_ok=is_ok)

checks.check_result.CheckResult.from_comparison classmethod 

from_comparison(
    provided: float,
    required: float,
    operator: Literal["<", "<=", "==", ">=", ">", "!="] = "<=",
) -> Self

Create a CheckResult from a direct comparison of provided and required values. Will automatically calculate unity_check, factor_of_safety, and is_ok.

Please note: When either provided or required is zero, or the operator is "==" or "!=", special handling is applied to avoid division by zero and ensure meaningful results. Unity check and factor of safety calculations are adjusted such that they yield either 0.0 or infinity in these edge cases, reflecting pass/fail status appropriately.

Example
  • CheckResult.from_comparison(provided=80, required=100, operator="<=") -> CheckResult with unity_check=0.8, factor_of_safety=1.25, is_ok=True
  • CheckResult.from_comparison(provided=120, required=100, operator="==") -> CheckResult with unity_check=inf, factor_of_safety=0.0, is_ok=False
  • CheckResult.from_comparison(provided=0, required=10, operator="<=") -> CheckResult with unity_check=0.0, factor_of_safety=inf, is_ok=True

Parameters:

  • provided (float) –

    The actual value from the design (e.g., applied load, stress).

  • required (float) –

    The allowable or required value (e.g., capacity, code required).

  • operator (str, default: '<=' ) –

    The comparison operator ("<", "<=", "==", ">=", ">", "!="). Default is "<=".

Returns:

  • CheckResult –

    A new CheckResult instance with the specified values.

Source code in blueprints/checks/check_result.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
@classmethod
def from_comparison(
    cls,
    provided: float,
    required: float,
    operator: Literal["<", "<=", "==", ">=", ">", "!="] = "<=",
) -> Self:
    """
    Create a CheckResult from a direct comparison of provided and required values.
    Will automatically calculate unity_check, factor_of_safety, and is_ok.

    Please note: When either `provided` or `required` is zero, or the operator is "==" or "!=", special handling is applied
    to avoid division by zero and ensure meaningful results. Unity check and factor of safety calculations are adjusted such
    that they yield either 0.0 or infinity in these edge cases, reflecting pass/fail status appropriately.

    Example
    -------
    - CheckResult.from_comparison(provided=80, required=100, operator="<=")
      -> CheckResult with unity_check=0.8, factor_of_safety=1.25, is_ok=True
    - CheckResult.from_comparison(provided=120, required=100, operator="==")
      -> CheckResult with unity_check=inf, factor_of_safety=0.0, is_ok=False
    - CheckResult.from_comparison(provided=0, required=10, operator="<=")
      -> CheckResult with unity_check=0.0, factor_of_safety=inf, is_ok=True

    Parameters
    ----------
    provided : float
        The actual value from the design (e.g., applied load, stress).
    required : float
        The allowable or required value (e.g., capacity, code required).
    operator : str, optional
        The comparison operator ("<", "<=", "==", ">=", ">", "!="). Default is "<=".

    Returns
    -------
    CheckResult
        A new CheckResult instance with the specified values.
    """
    return cls(provided=provided, required=required, operator=operator)

checks.check_result.CheckResult.from_factor_of_safety classmethod 

from_factor_of_safety(factor_of_safety: float) -> Self

Create a CheckResult from a factor of safety value (required/provided).

Parameters:

  • factor_of_safety (float) –

    The factor of safety (required / provided). Where values >= 1.0 indicate passing checks.

Example
  • CheckResult.from_factor_of_safety(factor_of_safety=1.25) -> CheckResult with factor_of_safety=1.25, unity_check=0.8, is_ok=True, other fields None

Returns:

  • CheckResult –

    A new CheckResult instance with factor_of_safety=factor_of_safety.

Source code in blueprints/checks/check_result.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
@classmethod
def from_factor_of_safety(cls, factor_of_safety: float) -> Self:
    """
    Create a CheckResult from a factor of safety value (required/provided).

    Parameters
    ----------
    factor_of_safety : float
        The factor of safety (required / provided).
        Where values >= 1.0 indicate passing checks.

    Example
    -------
    - CheckResult.from_factor_of_safety(factor_of_safety=1.25)
      -> CheckResult with factor_of_safety=1.25, unity_check=0.8, is_ok=True, other fields None

    Returns
    -------
    CheckResult
        A new CheckResult instance with factor_of_safety=factor_of_safety.
    """
    return cls(factor_of_safety=factor_of_safety)

checks.check_result.CheckResult.from_unity_check classmethod 

from_unity_check(unity_check: float) -> Self

Create a CheckResult from a unity check value (provided/required).

Parameters:

  • unity_check (float) –

    The ratio of provided to required (provided / required). Where values <= 1.0 indicate passing checks.

Example
  • CheckResult.from_unity_check(unity_check=0.8) -> CheckResult with unity_check=0.8, factor_of_safety=1.25, is_ok=True, other fields None

Returns:

  • CheckResult –

    A new CheckResult instance with unity_check=unity_check.

Source code in blueprints/checks/check_result.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@classmethod
def from_unity_check(cls, unity_check: float) -> Self:
    """
    Create a CheckResult from a unity check value (provided/required).

    Parameters
    ----------
    unity_check : float
        The ratio of provided to required (provided / required).
        Where values <= 1.0 indicate passing checks.

    Example
    -------
    - CheckResult.from_unity_check(unity_check=0.8)
      -> CheckResult with unity_check=0.8, factor_of_safety=1.25, is_ok=True, other fields None

    Returns
    -------
    CheckResult
        A new CheckResult instance with unity_check=unity_check.
    """
    return cls(unity_check=unity_check)