Conventions

In this section, we will describe the conventions used in the documentation and code.

Folders and file types

• Documentation is written in markdown.
• Tutorials are written in markdown.

File naming conventions

• Documentation files are named using CamelCase.
• Image files in the docs folder are named using snake_case
• Use lowercase 2d/3d (not 2D/3D) in file, function, and variable names, per PEP8.

Mathematical conventions

The imaginary unit will be denoted \(\mathfrak i\), \mathfrak i to avoid confusion with the index \(i\). Index symmetrization \(()\) and anti-symmetrization \([]\) will be used throughout. They are defined for an tensor \(A\) with two indices by

\[ A_{(ij)} = \frac{1}{2} (A_{ij} + A_{ji}), \]

\[ A_{[ij]} = \frac{1}{2} (A_{ij} - A_{ji}) \]

The Fourier transform of a field \(\psi\) will be denoted \(\psi_{\mathfrak f}\), \psi_{\mathfrak f}, and is defined as

\[ \psi_{\mathfrak f} (\mathbf k) = \int d^d r e^{-\mathfrak i \mathbf k \cdot \mathbf r} f(\mathbf r), \]

and the inverse is given by

\[ \psi(\mathbf r) = \frac{1}{(2\pi)^d} \int d^d k e^{\mathfrak i\mathbf k\cdot \mathbf r} \psi_{\mathfrak f}(\mathbf k), \]

where \(d\) is the spatial dimension.

Vectors \(\mathbf a, \mathbf b, \mathbf c, \boldsymbol \Omega\) are denoted using boldfont (\mathbf, \boldsymbol) , while rank 2 tensors vary more. Typical choices however are non-bold greek letters (\(\sigma\)) lower case Fraktur letters (\(\mathfrak h\), \mathfrak h) or capital letters (\(Q\)).

The dot product (\(\cdot\)) is a contraction over the last index

(\nabla \cdot \sigma)_i = \partial_j {\sigma}_{ij}

while the double dot product \(\dot \cdot\) is a contraction over the last two indices

\[ (\mathcal C \dot \cdot \mathfrak e)_ {ij} = \mathcal C_ {ijkl} \mathfrak e_ {kl} \]

Programming notation conventions

• PEP8 for python programming
• NumPy docstring format for documentation strings
• Function and variable names are always lowercase, with no exception for embedded proper nouns (e.g. calc_gaussian, conf_initial_condition_thomas_fermi, not calc_Gaussian, conf_initial_condition_Thomas_Fermi), matching the convention used by NumPy/SciPy/scikit-learn. Capitalization is reserved for class names.
• Import ordering should follow this pattern:
• Standard library imports
• Third-party library imports
• Local application imports
• Each group should be separated by a blank line
• dt is reserved for self.dt, the base system's own time step (or a value taken directly from it). Any other time-interval quantity — one that is computed against self.dt (e.g. divided by it to get a step count) or otherwise not literally the same value — is named delta_t (lowercase; PEP8 gives no exception for a capitalized Delta_t), not a copy of dt under a different name.
• Public function/method parameters are named descriptively even when the underlying physics literature or a docstring uses a bare mathematical symbol for the same quantity (e.g. a tangent_vector parameter for what a cited paper calls \(\hat T\), or thomas_fermi_radius for what's commonly written \(R_{tf}\)) — the symbol belongs in the equation/docstring, not the call signature. This also rules out ad hoc abbreviations standing in for the descriptive name (thomas_fermi_radius, not R_tf). This mirrors the descriptive-name convention already used for most parameters in this codebase (dipole_vector, charge_tolerance, etc.).

Stand-alone functions are documented as follows:

def function_name(
        arg1: arg1_type, 
        arg2: arg2_type, 
        arg3: Optional[arg3_type] = None,
        **kwargs: Any
        ) -> return_type:
    """Short description of the function (in the imperative mood).

    Optional longer description of the function.

    Parameters
    ----------
    arg1 : arg1_type
        Description of arg1. No need to state default values.
    arg2 : arg2_type
        Description of arg2.
    arg3 : arg3_type, optional
        Description of arg3. Defaults to None.
    kwargs : Any
        Description of additional keyword arguments.


    Returns
    -------
    return_type
        Description of the return value.

    Raises
    ------
    Exception
        Description of the exception.

    Examples
    --------
    >>> function_name(1, 2)
    3       
    """
    pass

If the function is a method of a comfit model, it should be documented as follows:

from typing import TYPE_CHECKING # Import necessary typing packages

if TYPE_CHECKING:
    from comfit.core.base_system import BaseSystem

# General packages
# Import necessary packages from the standard library, e.g.
# import numpy as np

# Comfit packages
# Import necessary packages from comfit from the subpackages, e.g. 
# from comfit.core import BaseSystem

def function_name(
        self: 'BaseSystem',
        arg1: arg1_type, 
        arg2: arg2_type, 
        arg3: Optional[arg3_type] = None
        ) -> return_type:
    """Short description of the function (in the imperative mood).

    Optional longer description of the function.

    Parameters
    ----------
    arg1 : arg1_type
        Description of arg1. No need to state default values.
    arg2 : arg2_type
        Description of arg2.
    arg3 : arg3_type, optional
        Description of arg3. Defaults to None.
    kwargs : Any (use backslash to escape the asterisk)
        Description of additional keyword arguments.

    Returns
    -------
    return_type
        Description of the return value.

    Raises
    ------
    Exception
        Description of the exception.

    Examples
    --------
    >>> function_name(1, 2)
    3       
    """
    pass

• markdownlint for markdown documents.