naming of physical quantities in python

Question

I would like to establish a good naming scheme for physical/mathematical quantities used in my simulation code. Consider the following example:

from math import *

class GaussianBeamIntensity(object):
    """
    Optical intensity profile of a Gaussian laser beam.
    """

    def __init__(self, intensity_at_waist_center, waist_radius, wavelength):
        """
        Arguments:

        *intensity_at_waist_center*: The optical intensity of the beam at the
            center of its waist in W/m^2 units.

        *waist_radius*: The radius of the beam waist in meters.

        *wavelength*: The wavelength of the laser beam in meters.

        """

        self.intensity_at_waist_center = intensity_at_waist_center
        self.waist_radius = waist_radius
        self.wavelength = wavelength
        self._calculate_auxiliary_quantities()

    def _calculate_auxiliary_quantities(self):
        # Shorthand notation
        w_0, lambda_ = self.waist_radius, self.wavelength

        self.rayleigh_range = pi * w_0**2 / lambda_
        # Generally some more quantities could follow

    def __call__(self, rho, z):
        """
        Arguments:

        *rho*, *z*: Cylindrical coordinates of a spatial point.
        """
        # Shorthand notation
        I_0, w_0 = self.intensity_at_waist_center, self.waist_radius
        z_R = self.rayleigh_range

        w_z = w_0 * sqrt(1.0 + (z / z_R)**2)
        I = I_0 * (w_0 / w_z)**2 * exp(-2.0 * rho**2 / w_z**2)
        return I

What consistent naming scheme would you propose for the physical properties (properties, function arguments etc.) in order to balance between readability and concise notation (that formulae remain relatively short)? Could you please refine the example above? Or perhaps propose a better scheme?

It would be nice to follow the guidelines of PEP8, remembering that "A Foolish Consistency is the Hobgoblin of Little Minds". It seems difficult to stick to descriptive names while obeying the traditional 80-character limit for line lengths.

Thank you in advance!

Kohn

What value do you really get from the 80 character limit anyway? It's not like you are going to send your code in an email back to the 1980's – Marven

@Klaus: 80 char limit is nice though; e.g., can have more files open on the screen and don't have to accomodate just one really long line taking up a bunch of screen real estate. (E.g., right now in xmonad on my two screens I have about 12 windows tiled; most with code cropping at ~90 chars or so.) – Dreiser

@jimbob I see your point, but I use an IDE. – Marven

@Klaus: this is the topic of another debate. See: #747353 – Kohn

cornail: Your code is well under the 80 character limit. What is it you are looking for? – Cohesion

this is a common mistake: expressive names != long names. Having too long names hurts both readability and expressiveness. – Northwestwards

@sukhbir: I have been thinking whether there is a better coding-style alternative for this "shorthand notation stuff", it isn't the 80 char limit that bothers me. See my comment on dawe's answer. – Kohn

@Lie Ryan: I would be glad if you could propose then a better solution in an answer. – Kohn

Random formula tips: I prefer foo**0.5 over sqrt(foo) and / e**(2 * bar) over * exp(-2 * bar). – Flycatcher

Answer 1

I think you've already found the good balance. Expressive names are important, so I totally agree with the use of wavelenght instead of lambda as a class attribute. This way the interface remains clear and expressive.

In a long formula, though, lambda_ is good choice as shorthand notation, because this is a commonly accepted and widely used notation for the wavelength in optics. I think when you implement a formula, what you want to do is staying as close as possible to the form of the equations you'd write on a piece of paper (or as they appear in an article etc).

In short: keep the interfaces expressive, the formulae short.

Drennen

When using this shorthand notation stuff, almost every method starts with these :) Indeed the interfaces are descriptive this way. What I am unsure about: the naming of the function arguments. They are mostly descriptive but long (see ctor), and the docstrings for them seem to show a certain degree of redundancy... – Kohn

@Kohn - There's nothing really wrong with having redundant function names and docstrings... Keep in mind that people are far more likely to read the function name than the docstring! Personally, I'd err on the side of long-ish, but expressive function names. – Juback

Answer 2

Use Python3 and you can use the actual symbol λ for a variable name.

I look forward to writing code like:

from math import pi as π

sphere_volume = lambda r : 4/3 * π * r**3

Chenee