Naming Conventions for FatPy Functions & Parameters

[Vybornak2]

Hi everyone,

Edit: changed naming for first, second principal stress, mean, amp stress

It's crucial to decide on consistent naming conventions. Establishing this early, in line with the spirit of Python's PEP 8 for readable code, will make the library easier to understand, use, and contribute to.

Fatigue analysis uses many specific terms and symbols (e.g., σ_a, R, S_e). While symbols are common in literature, clear, descriptive names are generally better for code clarity and maintainability. Therefore, the initial suggestion is to prioritize descriptive, verbose names over brevity or abbreviations, even if they are slightly longer. We should, of course, use standard Python snake_case.

Applying this principle, let's consider some examples:

1. Function Names: We'd lean towards explicit names like calculate_von_mises_stress or calculate_stress_amplitude rather than von_mises or stress_amp. Thoughts?
2. Parameter Names: This suggests preferring stress_amplitude, mean_stress or potentionally sg_mean, sg_amp over sg_a, sg_m or sa,sm. Does this seem right?
3. Common Symbols vs. Verbosity: Even with this preference, are there universally understood symbols that might be acceptable exceptions for parameters?
   • stress_ratio vs. R?
   • youngs_modulus vs. E?
   • poissons_ratio vs. nu?
   • ultimate_strength vs. R_m?
   • (Where should we draw the line? Maybe stick to full names for properties?)
4. Indexed Names: For results like principal stresses, first_principal, second_principal seems most descriptive. Agree?
5. Consistency: Are there other key fatigue terms where we need to define the standard verbose name now?

Goal: To establish naming conventions that prioritize clarity and readability for all users, making the code self-explanatory where possible.

What are your thoughts on this "clarity first" approach? Do you agree with leaning towards verbosity? What are your preferences on the specific examples, especially regarding common symbols?

[gokberkozcicek]

Python is a indentation based language. I think we have to keep the naming convention as small as possible. Common symbols will increase the readibility of the code. For example lets assume that we are trying to write method for signed von mises.

long form
signed_von_misses=((principal_stress_1+principal_stress_2+principal_stress_3)/abs((principal_stress_1+principal_stress_2+principal_stress_3)+1e-5))*von_mises()
short form
svm=((s1+s2+s3)/abs(s1+s2+s3+1e-5))*vm()

[Vybornak2]

Yes, you are qute right. It is basically bevity vs readability.
But I think you can still split expressions to logical parts. But I too do not like too long names, so finding balance would be great, if common short term is not applicable.

For principal stresses, this is quite easy. I still prefer first_principal (I had to correct original post)
What troubles me more are maybe some other variables/names, that might not be as unified. So I am wondering what notation to use generally to have unified approach.

You also hit a bit problematic part here
stress von mises vs signed
I would bet, that this could cause lot of confusion.

So for many things, I would like to go with simple conventional naming.

When I also take your example, you can do it like this, which does definitely not look too bad to me.
Especially when formula gets long, I recommend splitting it like this for more clarity.

note: python 3.12 generic type notation is used

import numpy as np

def calculate_signed_von_mises_principal[T: np.floating](
    first_principal: NDArray[T],
    second_principal: NDArray[T],
    third_principal: NDArray[T],
) -> NDArray[T]:
    unsigned_von_mises = np.sqrt(
        (
            (first_principal - second_principal) ** 2
            + (second_principal - third_principal) ** 2
            + (third_principal - first_principal) ** 2
        )
        / 2.0
        + 1e-12
    )
    hydrostatic_stress = (first_principal + second_principal + third_principal) / 3.0
    signed_von_mises = np.copysign(unsigned_von_mises, hydrostatic_stress)

    return signed_von_mises  # type: ignore

[Vybornak2]

Naming suggestion:

Calculation functions

Should utilize calc_ prefix in the fucntion name signature.

import numpy as np
from numpy.typing import NDArray

def calc_stress_von_mises[T: NDArray[np.floating]](stress_vector: T) -> T:
    """ Calculate the von Mises stress from the stress vector.

    Args:
        stress_vector (T): Stress vector of shape (n, 6) where n is the number of points.
    """
    svm = np.sqrt(
        0.5 * ((stress_vector[:, 0] - stress_vector[:, 1]) ** 2
               + (stress_vector[:, 1] - stress_vector[:, 2]) ** 2
               + (stress_vector[:, 2] - stress_vector[:, 0]) ** 2
               + 6 * (stress_vector[:, 3] ** 2 + stress_vector[:, 4] ** 2 + stress_vector[:, 5] ** 2))
    )
    return svm

Functions input - Voigt notation vs components

Stress vector in voigt notation is prefered over multiple components vectors / stress tensor

def correct_function[T: NDArray[np.floating]](stress_vector: T) -> T:
    """ Description of function

    Args:
        stress_vector (T): Stress vector of shape (n, 6) where n is the number of points.
    """
    pass

def incorrect_function[T: NDArray[np.floating]](s11: T, s22: T, s33: T, s12: T, s23: T, s13: T) -> T:
    """ Description of function

    Args:
        s11 (T): Normal stress ($S_{11}$) vector (n,) where n is the number of points.
        ...
        s13 (T): Shear stress ($S_{13}$) vector (n,) where n is the number of points.
    """
    pass

Stresses

mean_stress
stress_amp

first_principal_stress
second_principal_stress
third_principal_stress

Material parameters:

elastic_modulus
shear_modulus
ultimate_tensile_strength
poisson_ratio
yield_strength

[Vybornak2]

I would like to additionally correct myself, as Generic type annotation from python 3.12 will not be initially implemented as this is not required currently. Maybe in future if there will be such requirement, we could implement something of that sort.