SEP 2 — Nomenclature guidelines#

Authors:

Klemen Zaletelj <klemen.zaletelj@fs.uni-lj.si>, Janko Slavič <janko.slavic@fs.uni-lj.si>

Status:

Draft

Type:

Process

Created:

2021-03-15

Abstract#

The nomenclature guidelines for SDyPy are presented for better interoperability of the packages/modules.

Motivation#

The nomenclature is often not consistent for different packages which affects the user experience when combining the use of multiple packages.

Detailed description#

SDyPy nomenclature follows the python guidelines, presented in PEP 8.

General guidelines#

  • As is stated in PEP 8, the code is read much more often than it is written. The names of the variables should therefore be as descriptive as possible. Examples:

    a = 4 # Not good

rectangle_height = 4 # Good

    With most code editors enabling the use of autocomplete, the length of the variables does not present a major issue for code writing.

  • When combining multiple words into a variable name, the term with a broader meaning should be on the first place. The more defining term comes next. This improves the readability of the code, enabling the reader to immediately understand what the main purpose of the variable is. Examples:

    freq_upper
freq_lower
damping_viscous
damping_hysteretic

    It should be said, that the it is up to the user to determine what is the more broader term.

Common variables in structural dynamics#

Despite the general guidelines written above, the variables which are broadly used in structural dynamics can be an exception. To avoid different variable names (e.g. sampling_frequency, freq_sampling), the conventions given below should be used.

Parameter

Symbol

Unit

Description

Frequency limits

freq_upper, freq_lower

Frequency Response Function

frf

Different forms of the frequency response function are possible (receptance, mobility, accelerance) and can be given other names. When the frequency response function is referenced in arbitrary form, this variable name should be given.

Frequency vector

freq

Hz

Frequency vector in rad/s

freq_rad

rad/s

Natural frequency

natural_freq

Hz

Sampling frequency

fs

Hz

This name is not descriptive; however, it is commonly used in other packages (e.g. scipy)

Time step

dt

second

FRF form

frf_form

Form of the frequency response function: 'receptance', 'mobility' or 'accelerance'. Canonical name at the sdypy level; backend parameter names are out of scope.

Young’s modulus

young_modulus

Pa

Fixed compound term; the broader-term-first rule does not reorder it.

Poisson’s ratio

poisson_ratio

Fixed compound term.

Density

density

kg/m^3

Naming of public objects#

The guidelines above cover variables. For all other public names in SDyPy first-level packages the following conventions apply (PEP 8, made explicit):

  • Modules and packages: snake_case words. Established acronym sub-package names fixed by SEP 3 / SEP 4 (EMA, FRF, OMA) stay uppercase.

  • Classes: CapWords; acronyms keep their uppercase form inside CapWords names (FRF, not Frf).

  • Functions, methods and parameters: snake_case; acronyms are written in lowercase inside snake_case names (add_frf, frf_form). Exception: established criterion functions may be the bare uppercase acronym (MAC, MSF, MCF).

  • Constants: ALL_CAPS.

  • Framework exemption: names mandated by an external framework keep that framework’s casing (e.g. the Qt closeEvent override).

Public API surface#

Every first-level package declares its public API with an explicit __all__ in its sdypy/<name>/__init__.py. Only the names curated in __all__ are supported API; any other module attribute is an implementation detail. Packages that wrap a backend re-export the curated names explicitly instead of star-importing the backend, so third-party and standard-library names never enter the public surface.

Deprecation policy#

When a public name is renamed to conform to these guidelines, the old name is kept as an alias that emits DeprecationWarning for all of v1.x. Removal of a deprecated alias happens no earlier than v2.0. New code uses the canonical names only.

Discussion#

This section may just be a bullet list including links to any discussions regarding the SEP:

  • This includes links to mailing list threads or relevant GitHub issues.

References and Footnotes#