struct_utils 0.0.1__py3-none-any.whl

struct_utils/__init__.py

@@ -0,0 +1,2 @@
+#just to keep things importable.
+

struct_utils/general_utils/__init__.py

@@ -0,0 +1,2 @@
+from .logprint import (logprint)
+

struct_utils/general_utils/logprint.py

@@ -0,0 +1,132 @@
+import logging
+from datetime import datetime
+from pathlib import Path
+
+__all__ = ['setup_logging']
+
+def logprint(
+    name: str = 'app',
+    *,
+    verbose: bool = False,
+    log_dir: str = '/tmp',
+    log_path: str | None = None,
+    file_level: int = logging.DEBUG,
+    console_level: int | None = None,
+    fmt: str = '%(asctime)s  %(name)s  %(levelname)-8s  %(message)s',
+    datefmt: str = '%G%V_%u_%H_%M_%S',
+) -> logging.Logger:
+    """Configure and return a named logger.
+
+    Parameters
+    ----------
+    name : str
+        Logger name (also used in the default filename).
+    verbose : bool
+        If True, add a StreamHandler so output also appears on the console.
+    log_dir : str
+        Directory for the auto-generated log file (default /tmp).
+    log_path : str | None
+        Explicit log file path.  Overrides log_dir + auto-naming.
+    file_level : int
+        Minimum level written to the file (default DEBUG — capture everything).
+    console_level : int | None
+        Minimum level printed to console.  Defaults to DEBUG if verbose,
+        but you can set e.g. logging.WARNING for quieter console output.
+    fmt : str
+        Log format string.
+    datefmt : str
+        Timestamp format for log lines.
+
+    Returns
+    -------
+    logging.Logger with an extra attribute `log_path` (pathlib.Path or None).
+    `log_path` is None when file logging failed and the logger fell back to
+    console-only output.
+    """
+    logger = logging.getLogger(name)
+
+    # Avoid stacking duplicate handlers on repeated calls
+    if logger.handlers:
+        logger.log_path = getattr(logger, 'log_path', None)
+        return logger
+
+    logger.setLevel(logging.DEBUG)  # let handlers decide what to pass
+
+    formatter = logging.Formatter(fmt, datefmt=datefmt)
+
+    # ── File handler (always attempted) ──────────────────────────
+    p = None
+    try:
+        if log_path is None:
+            ts = datetime.now().strftime('%Y%m%d_%H%M%S')
+            p = Path(log_dir) / f'{name}_{ts}.log'
+        else:
+            p = Path(log_path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+
+        fh = logging.FileHandler(str(p), mode='w', encoding='utf-8')
+        fh.setLevel(file_level)
+        fh.setFormatter(formatter)
+        logger.addHandler(fh)
+
+    except Exception as exc:
+        # File logging unavailable (bad path, permissions, read-only fs, …)
+        # Add a fallback StreamHandler only if verbose hasn't already arranged one.
+        p = None
+        if not verbose:
+            verbose = True   # let the normal console block below handle it
+            ch_fallback = logging.StreamHandler()
+            ch_fallback.setLevel(file_level)
+            ch_fallback.setFormatter(formatter)
+            logger.addHandler(ch_fallback)
+        logger.warning(
+            f'File logging unavailable ({exc}); falling back to console.'
+        )
+
+    # ── Console handler (when verbose or after fallback) ─────────
+    if verbose:
+        ch = logging.StreamHandler()
+        ch.setLevel(console_level if console_level is not None else logging.DEBUG)
+        ch.setFormatter(formatter)
+        logger.addHandler(ch)
+
+    # Stash path on the logger for callers to reference (None if fallback)
+    logger.log_path = p
+    if p is not None:
+        logger.info(f'Log file: {p}')
+
+    return logger
+""" 
+## EXAMPLE USAGE:
+from shared_helpers import logprint
+
+# Basic usage — file only
+log = logprint('my_app', verbose=1)
+log.debug('Starting up')
+log.info('Processing data')
+log.warning('Disk usage high')
+log.error('Failed to connect')
+
+# Verbose — also prints to console
+log = logprint('my_app', verbose=True)
+log.info('You will see this in terminal too')
+
+# Custom log directory
+log = logprint('my_app', log_dir='/var/log/myproject', verbose=True)
+
+# Explicit path
+log = logprint('my_app', log_path='/tmp/my_app_debug.log')
+
+# Quieter console (only warnings+), but full debug to file
+log = logprint(
+    'my_app',
+    verbose=True,
+    console_level=logging.WARNING,
+    file_level=logging.DEBUG,
+)
+log.debug('Goes to file only')
+log.warning('Goes to both file and console')
+
+# Access the log file path
+log = logprint('pipeline', log_dir='/tmp/logs')
+print(f'Logging to: {log.log_path}') """

struct_utils/software_utils/__init__.py

@@ -0,0 +1,3 @@
+from .folder_structure_tree import (
+    folder_structure_tree
+)

struct_utils/software_utils/folder_structure_tree.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+def folder_structure_tree(path=Path("."), prefix=""):
+    r"""
+    #usage example: 
+    location_to_map=Path(r"C:\Users\USER\Desktop")
+    print(location_to_map.resolve())
+    folder_structure_tree(location_to_map)
+    """
+    entries = sorted(path.iterdir(), key=lambda e: (e.is_file(), e.name))
+    for i, entry in enumerate(entries):
+        connector = "└── " if i == len(entries) - 1 else "├── "
+        print(prefix + connector + entry.name)
+        if entry.is_dir():
+            extension = "    " if i == len(entries) - 1 else "│   "
+            folder_structure_tree(entry, prefix + extension)
+
+
+
+
+
+
+
+

struct_utils/structural_utils/NASA_TM_108378_fitting_factor.py

@@ -0,0 +1,228 @@
+## =============================================================================
+## 
+#
+## Reference:
+## H. M. Lee, "Shear-Joint Capability Versus Bolt Clearance", NASA TM-108378 (1992).
+## PDF: https://ntrs.nasa.gov/api/citations/19930003231/downloads/19930003231.pdf
+## =============================================================================
+"""
+#assumes a single fastener needs to penetrate a single abutment by CL/2 to bring other fasteners in contact with the hole edge. For two plates, penetration is CL. Distribution between plates is a function of contact stiffness.
+****************************************************************************Terms*********************************************************************************************
+| Symbol                 | Description                                     | Units | Notes / Physical Meaning                                                                |
+| ---------------------- | ----------------------------------------------- | ----- | --------------------------------------------------------------------------------------- |
+| D_b                    | Bolt shank diameter                             | in    | Diameter of the fastener                                                                |
+| D_h                    | Hole diameter in plate                          | in    | D_h = D_b + CL                                                                          |
+| CL                     | Clearance                                       | in    | Gap between bolt and hole; free play that must be taken up                              |
+| b                      | Hertzian contact width                          | in    | Width of contact at the bolt/plate interface                                            |
+| b_i                    | Initial Hertzian width                          | in    | Computed iteratively from initial trial shear V_i.                                     |
+| b_e                    | Hertzian width at full embedment                | in    | Assumed b_e=D_b in paper. Technically should be computed recursively for accuracy.      |
+| dy / ΔY                | Deformation distance                            | in    | Distance fastener must yield to take up clearance (eq. 4)                               |
+| dy_e                   | ΔY at full embed (closing CL so others engage)  | in    | Distance needed for full embedment to start load sharing with other bolts               |
+| E_b                    | Modulus of elasticity of bolt                   | psi   | Stiffness of the bolt material                                                          |
+| v_b                    | Poisson's ratio of bolt                         | -     | Typically ~0.3 for steel                                                                |
+| E_h                    | Modulus of elasticity of abutment plate         | psi   | Governs Hertzian compliance (e.g., aluminum)                                            |
+| v_h                    | Poisson's ratio of abutment plate               | -     | Typically ~0.33 for aluminum                                                            |
+| V_i                    | Initial trial shear                             | lbf   | Arbitrary starting value to compute initial Hertzian width                              |
+| V_e                    | Embedment shear                                 | lbf   | Shear to completely embed bolt into abutment (eq. 8)                                    |
+| V_CL_star              | Clearance closure shear helper value.           | lbf   | Shear needed to take up bolt-hole clearance, not accounting for flange thicknesses      |
+| V_CL                   | Clearance closure shear adjusted for two plates | lbf   | Shear needed to take up bolt-hole clearance, accounting for flange thickness            |
+| V_ult                  | Ultimate shear of bolt                          | lbf   | Material shear limit of the bolt                                                        |
+| bolt_limit_shear   | Limit shear in fastener                         | lbf   | Shear load of single fastener prior to accounting for clearance.                        | 
+| joint_limit_shear      | Limit shear in fastener                         | lbf   | Shear load of all fasteners (accounting for n) prior to accounting for clearance.       | 
+| T1                     | Thickness of abutment plate 1                   | in    | Used to scale V_CL for series plates                                                    |
+| T2                     | Thickness of abutment plate 2                   | in    | ^                                                                                       |
+| T_i                    | Arbitrary dy_e guess for V_CL_star calc         | in    | Used only in initial Hertz calculation (eq. 6); should not be used in final V_CL calc   |
+| n                      | Number of fasteners                             | -     | Number of bolts in the joint                                                            |
+| FOS                    | Factor of safety                                | -     | Usually 1 in TM examples                                                                |
+"""
+
+
+##---
+##-Calculations
+##-----
+import math
+
+#Material properties                                  #E (lb/in^2), Poissons, F_su (psi). 
+steel_from_paper           = [30.0e6, 0.30, 95e3]
+aluminum_from_paper        = [10.0e6, 0.33, 51e3]     #F_SU for AL was never given.
+
+MP35N_from_paper           = [34.0e6, 0.34, 145e3]
+metal_4130_from_paper      = [30.0e6, 0.30, 0]        #Guess? poorly documented in paper.
+
+Inco_steel_AMS5662         = [29.4e6, 0.29, 125e3]       
+A286_steel_AMS5737         = [29.1e6, 0.31, 95e3]
+titanium_AMS4928           = [16.9e6, 0.31, 95e3]
+
+class_8_fastener = [30e6, 0.31, 85e3]
+steel_A572_G50   = [30e6, 0.31, 50e3]
+
+
+def NASA_TM_108378_fitting_factor (input_matrix):                #input={D_b, CL, n, FOS, bolt_material, f1_mat, f2_mat, f1_thick, f2_thick, bolt_limit_shear}
+    """
+    Programmatic implementation of NASA TM-108378 (https://ntrs.nasa.gov/api/citations/19930003231/downloads/19930003231.pdf). Validated output against NASA_TM_108378 table 5. Returns a knockdown for fitting factor due to hole clearance.
+    Warning: This calculator should only be used for assessing the strength of unshimmed bolted joints, with threads not in the shear plane. This calculator only assesses the increased shear load in the bolt, and does not assess flange health, tensile loading, or any other factors. If stacking more than two flanges, it is conservative to define a material with the maximum Poissons and maximum Youngs modulus in the stackup to define bounding properties. The thickness of that composite flange should be input as the sum of the constituent thicknesses.
+    Material input matrices are formatted as: [E, Poissons, F_su]. Inputs require consistent base units.
+
+    Example case:
+
+    input_matrix_validation2= {                             # Appendix D validation.
+    "D_b"                   : 0.375,                        # Units: Inches | LMC fastener diameter.
+    "CL"                    : 0.016,                        # Units: Inches | CL=D_h-D_b (diameter of hole ho minus diameter of bolt). Larger values of CL are conservative.
+    "n"                     : 4,                            # Units: Qty    | Number of fasteners.
+    "FOS"                   : 1,                            # Usually = 1
+    "bolt_material"         : [34.0e6, 0.34, 145e3],        # See material names at top of sheet. Verify material spec aligns with your use.
+    "f1_mat"     : [30.0e6, 0.30, 0],                       # ^
+    "f2_mat"     : [30.0e6, 0.30, 0],                       # ^
+    "f1_thick"    : 0.4,                                    # Units: Inches | MMC thickness.
+    "f2_thick"    : 0.375,                                  # ^
+    "bolt_limit_shear"  : 16014                             # Units: lbf    | Max nominal shear loading for a single fastener, accounting for peaking, do not enter fastener strength.
+    }
+    Output_clearanced_fitting_factor=NASA_TM_108378_fitting_factor(input_matrix_validation2)
+
+    """
+#--
+    ## Inputs and trivial identities.
+    D_b = input_matrix["D_b"]
+    CL  = input_matrix["CL"]                                #maximum distance the bolt can be from an edge of the hole.
+    D_h = D_b + CL                                          #hole diameter
+    n   = input_matrix["n"]                                 #number of fasteners, more fasteners is a greater knockdown but log-ish impact.
+    FOS = input_matrix["FOS"]
+    bolt_material = input_matrix["bolt_material"]
+    F_su = bolt_material[2]                                 #units psi, usually 60% of minimum tensile strength.
+    E_b = bolt_material[0]; poissons_b=bolt_material[1]
+    V_ult = 0.25 * (math.pi) * F_su * D_b**2
+#-- 
+    ## Flange properties.
+    f1_mat = input_matrix["f1_mat"]; f2_mat = input_matrix["f2_mat"]
+    T1 = input_matrix["f1_thick"];               T2 = input_matrix["f2_thick"]
+    E_h = max(f1_mat[0], f2_mat[0])
+    poissons_h = max(f1_mat[1], f2_mat[1])
+#--
+    ## Fastener properties.
+    try:
+        bolt_limit_shear=input_matrix["bolt_limit_shear"]
+    except: #unconservative assumption, useful when comparing results to paper.
+        bolt_limit_shear=V_ult
+        print('Assuming limit_shear=V_ult')
+    joint_limit_shear = n*bolt_limit_shear
+
+#--
+    """
+    note to self: looks like the paper used V_i/T in places that asked for V_i, and did not have T_i in the b_i equation.
+    Y_i is calculated the same as the paper, and sigma_e_max=0.798*sqrt(AG35/(Dh*Db/CL)/CE) where CE=(1-poissons_b**2)/E_b+(1-poissons_h**2)/E_h). This approach allows the V_CL* they calculate to represent shear force per unit length, which they can then adjust for T1 and T2. For the same inputs as Testcase2, the calc gives 1.163 for clearanced fitting factor and 18624 on adjusted load on fastener, and ultimate joint capability=53623, and original limit shear=64059 (through joint, n*single bolt limit). The limit shear is only used in the logic checks and factors calcs. Factors are calculated against joint limit shear, not fastener limit shear.
+    """
+    ## Arbitrary initial conditions for equations
+    V_i = 100                                               #arbitrary initial shear force to find initial deformation, will be used to compute V_e later. Changing this doesn't impact the final result.
+    T_i = max(T1,T2)                                        #arbitrary initial thickness.
+#--
+    ## Main relevant equations from NASA TM-108378
+    def eq_4(b):                                            #distance fastener has to yield to take up CL so other fasteners start to share loading, eq4.
+        dy = 0.5*((D_h**2-b**2)**(0.5)-(D_b**2-b**2)**(0.5)-CL)
+        return dy
+    def eq_6(V, T_i):                                       #width of hertzian contact defined by hertzian equation, eq6.
+        b = 1.6*(((V*D_h*D_b)/(T_i*CL))*((1-poissons_b**2)/E_b+(1-poissons_h**2)/E_h))**(0.5)
+        return b
+    def eq_8(V_i, b_i):                                     #shear to completely embed the bolt shank diameter in the AL abutment. Eq8.
+        V_e = V_i*(D_b/b_i)**2
+        return V_e
+#--
+    ## Actually solving the problem
+    b_i  = eq_6(V_i, T_i)                                   #width of initial hertzian contact.
+    dy_i = eq_4(b_i)                                        #distance fastener has to yield to take up CL, eq4.
+    V_e  = eq_8(V_i, b_i)                                   #shear to completely embed the bolt shank diameter in the AL abutment. Eq8.
+    b_e  = D_b                                              #eq_6(V_e) #width of hertzian contact defined by hertzian equation, eq6. B_e as using V_embedded as input.
+    dy_e = eq_4(b_e)                                        #distance fastener has to yield to take up CL, eq4.
+    V_CL_star = V_e * CL / (2 * dy_e)                       #last equation from figure 4. shear such that the initial Hertzian width leads to exactly the deformation needed to close the gap. Should be solved iteratively to avoid impacting the value of V_CL
+    V_CL = (V_CL_star / T_i) * (T1 * T2) / (T1 + T2)        #equation from below figure 6. Paper poorly presents this equation, ignores T_i. It represents the force needed to close the gap. Applies if there are two abutment plates.
+
+#--
+    ## Debugging print statements:
+    for name, val in [("V_ult", V_ult),  
+                     #("b_i", b_i), ("dy_i", dy_i),("V_e", V_e), ("V_CL_star", V_CL_star), #arbitrary values given T_i and V_i
+                      ("dy_e", dy_e),  ("V_CL", V_CL)]:
+        print(f"{name}: {val:.7f}", end="\n")
+    print()  # final newline
+#--
+    ## Calculating Clearanced_fitting_factor
+    if joint_limit_shear<=V_CL:
+        Adjusted_load_on_fastener=joint_limit_shear                       #one fastener takes all the load as the shear doesn't close the gap
+    else:
+        Adjusted_load_on_fastener=V_CL+(joint_limit_shear-V_CL)/n         #shear closes the gap, afterwards all load is shared evenly between the fasteners.
+    
+    #Capability_perc1 = 1 - ((n-1)*FOS*V_CL)/(n * V_ult) #joint capability relative to no clearance design, found on P16. Lines up with appendix B.
+    #pei=-1.2695*10**9*CL**3+9.5361*10**7*CL**2+4.9919*10**5*CL-146.7 #appendix A
+    #Capability_perc2=1/(1-pei*((n-1)*FOS*T1*T2*D_b**2/((T1+T2)*n*V_ult))) #not giving me the correct answer for appendix B, eben when I get the right answer for V_CL
+
+#--
+    ## Logic checks and final print statements.
+    if bolt_limit_shear>V_ult:       #errors if there is an input error and does not print any calculated values.
+        print("ERROR in inputs: bolt_limit_shear is greater than V_ult. \n bolt_limit_shear = ", bolt_limit_shear, "\n V_ult = ", V_ult)
+    else:                       
+        if Adjusted_load_on_fastener>V_ult/FOS:
+            print("Fastener potentially overloads (accounting for FOS provided). Adjusted_load_on_fastener > V_ult \n      Adjusted_load_on_fastener = ", Adjusted_load_on_fastener, "\n     V_ult = ",  V_ult)
+#--
+        if joint_limit_shear<=V_CL:
+            print("Clearanced fastener takes the whole load because joint_limit_shear < V_CL")
+        else:
+            print("Joint will engage all fasteners because joint_limit_shear > V_CL")
+        if V_ult/FOS<=V_CL: #we do not close the gap prior to reaching ult, so other fasteners never share the load.
+            Adjusted_joint_capability=V_ult/FOS
+            print("All load potentially goes through a single fastener, gap is not closed")
+        else:
+            Adjusted_joint_capability=(n*V_ult/FOS)-((n-1)*V_CL)   #eq 12
+            print("All load potentially goes through a single fastener, gap is not closed")
+        rel_adjusted_joint_capability=Adjusted_joint_capability/(n*V_ult/FOS)
+        
+        Clearanced_fitting_factor=Adjusted_load_on_fastener/(bolt_limit_shear) #does not account for all fitting factor, multiply this by your other fitting factor contributions.
+
+#--
+    #if inputs are good, prints adjusted shear values:
+    print(f"Adjusted shear load on fastener: {Adjusted_load_on_fastener:.0f}")
+    print(f"Adjusted_joint_capability : {Adjusted_joint_capability:.0f}")
+    print(f"Joint capability relative to no clearance design: {rel_adjusted_joint_capability:.3f}")
+    print(f"Clearanced fitting factor (No FOS applied): {Clearanced_fitting_factor:.3f}")
+
+    return Clearanced_fitting_factor
+#----------------------------------------------------------------------------
+#### USER INPUTS->
+#----------------------------------------------------------------------------
+
+"""
+Program function: Programmatic implementation of NASA TM - 108378 (https://ntrs.nasa.gov/api/citations/19930003231/downloads/19930003231.pdf). Validated output against NASA_TM_108378 table 5. Returns a knockdown for fitting factor due to hole clearance.
+
+
+Warning: This calculator should only be used for assessing the strength of unshimmed bolted joints, with threads not in the shear plane. This calculator only assesses the increased shear load in the bolt, and does not assess flange health, tensile loading, among other factors. If stacking more than two flanges, define a new material near the top of this script with the maximum poissons and maximum Youngs modulus in the stackup. The thickness of that composite flange should be input as the sum of the constituent thicknesses.
+"""
+
+input_matrix_validation1= {                             # Table 5 validation.
+"D_b"                   : 0.196,                        # Units: Inches | LMC fastener diameter.
+"CL"                    : 0.02,                         # Units: Inches | CL=D_h-D_b (diameter of hole ho minus diameter of bolt). Larger values of CL are conservative.
+"n"                     : 2,                            # Units: Qty    | Number of fasteners.
+"FOS"                   : 1,                            # Usually = 1
+"bolt_material"         : steel_from_paper,             # See material names at top of sheet. Verify material spec aligns with your use.
+"f1_mat"     : aluminum_from_paper,          # ^
+"f2_mat"     : aluminum_from_paper,          # ^
+"f1_thick"    : 0.1,                          # Units: Inches | MMC thickness.
+"f2_thick"    : 0.1,                          # ^
+"bolt_limit_shear"  : 2100                          # Units: lbf    | Max nominal shear loading for a single fastener, accounting for peaking, do not enter fastener strength.
+}
+
+Output_clearanced_fitting_factor=NASA_TM_108378_fitting_factor(input_matrix_validation1)
+
+input_matrix_validation2= {                             # Appendix D validation.
+"D_b"                   : 0.375,                        # Units: Inches | LMC fastener diameter.
+"CL"                    : 0.016,                        # Units: Inches | CL=D_h-D_b (diameter of hole ho minus diameter of bolt). Larger values of CL are conservative.
+"n"                     : 4,                            # Units: Qty    | Number of fasteners.
+"FOS"                   : 1,                            # Usually = 1
+"bolt_material"         : MP35N_from_paper,             # See material names at top of sheet. Verify material spec aligns with your use.
+"f1_mat"     : metal_4130_from_paper,        # ^
+"f2_mat"     : metal_4130_from_paper,        # ^
+"f1_thick"    : 0.4,                          # Units: Inches | MMC thickness.
+"f2_thick"    : 0.375,                        # ^
+"bolt_limit_shear"  : 16014                         # Units: lbf    | Max nominal shear loading for a single fastener, accounting for peaking, do not enter fastener strength.
+}
+
+Output_clearanced_fitting_factor=NASA_TM_108378_fitting_factor(input_matrix_validation2)
+# To increase Conservatism, choose:
+# min(D_b, bolt_limit_shear, bolt_material[2])
+# max(n, CL, FOS, f1_thick, f2_thick, f2_mat[0:1], f2_mat[0:1], bolt_material[0:1])

struct_utils/structural_utils/__init__.py

@@ -0,0 +1,17 @@
+#this file controls the "API level imports"
+#The double dot represents one level up in the folder hierarchy.
+#The single dot represents the current package or directory.
+from .bolt_pattern_elastic_method import (
+    Bolt,
+    AppliedLoad,
+    BoltResult,
+    BoltPatternAnalysis,
+    bolt_pattern_force_distribution,
+    plot_bolt_pattern_3d,
+    print_results,
+)
+from .margin_table import add_row, print_table
+from .shared_helpers import von_mises
+from .NASA_TM_108378_fitting_factor import NASA_TM_108378_fitting_factor
+
+