All physics/equation based functions should have complete docstring

[je-cook]

Description

All functions that involve some implicit physics or equation should be referenced and/or have the equation in the docstring.

• The equation is usually written in the computationally fastest form in the body of the code, not the easiest form to read. Therefore it's beneficial to add the explicit equation in latex expression.

• References will enable us to trace some decisions in the future.

Running Updates (checked when complete, i.e., modified or read to ensure references/equations are present):

bluemira.balance_of_plant:

• [x] calculations
• [x] error
• [x] plotting
• [x] steady_state - we could put equations from NeutronPowerStrategy and RadChargedPowerStrategy in the docs but they are simple to follow in the code.

bluemira.equilibria.coils.:

• [ ] _coil
• [ ] _field
• [ ] _grouping
• [ ] _tools

bluemira.equilibria:

• [x] grad_shafranov
• [x] physics

bluemira.geometry :

• [ ] coordinates

bluemira.magnetostatics.:

• [ ] greens
• [ ] semianalytic_2d

bluemira.materials.:

• [x] cache
• [ ] constants
• [x] error
• [x] material
• [ ] mixtures
• [ ] tools

bluemira.plasma_physics.:

• [x] collisions
• [x] reactions
• [x] rules_of_thumb
• [x] scaling_laws

bluemira.radiation_transport.:

• [ ] advective_transport
• [ ] error
• [ ] flux_surface_maker
• [ ] midplane_temperature_density
• [ ] radiation_profile
• [ ] radiation_tools

bluemira.structural:

• [ ] element

[OceanNuclear]

Note to self: while I'm solving this issue, I will also try to add ~ into all instances of :class: found in the docstrings, so that they are properly linked.

[OceanNuclear]

• materials
  • [x] material
• builders
  • [x] tf_coils
• geometry
  • [x] parameterisations
  • [x] optimisation._optimise
  • [x] coordinates (still needs equations for normal_vector and get_bisection_line)
  • [x] tools (spline/ bezier equations; possibly insert some pictures for signed distances)
• optimisation
  • [x] _optimise
  • [x] _optimiser
  • [x] _nlopt.optimiser
• plasma_physics
  • [x] reactions
  • [x] collisions
  • [x] scaling_laws
  • [x] rules_of_thumb (only missing some equations)
• utilities
  • [x] opt_variables
  • [x] tools (levi_civita_tensor missing)
• balance_of_plant
  • [x] steady_state (partially done)
  • [x] calculations (partially done)
• equilibria
  • [x] coils._coil (volume/area equations missing)
  • [ ] coils._field
  • [ ] coils._tools (make_mutual_inductance_matrix may need to reference circular_coil_inductance_elliptic; need equation for get_max_current)
  • [ ] fem_fixed_boundary.fem_magnetostatic_2D
  • [ ] fem_fixed_boundary.file
  • [ ] fem_fixed_boundary.utilities
  • [x] optimisation.constraint_funcs
  • [ ] optimisation.constraints
  • [ ] optimisation.problem
  • [ ] optimisation.objectives (latex-ify; possibly reference?; explain the meaning of gamma)
  • [ ] optimisation.harmonics
  • [ ] boundary (optional: add equation to apply_boundary)
  • [x] equilibrium
  • [ ] file (lines that uses derive* functions needs equations/reference?)
  • [x] find
  • [ ] find_legs (reference and equations)
  • [ ] flux_surfaces (reference and equations)
  • [ ] grad_shafranov (equation?)
  • [ ] grid (equations missing from grid::volume_integral and grid::revolved_volume)
  • [ ] num_control (psi needs equation: especially for _pgreen()/reference)
  • [ ] physics (missing some equations; missing some references to existing equations)
  • [ ] plasma (Bz, Bp etc. equations missing)
  • [ ] profiles (pressures needs equation)
  • [ ] run
  • [ ] shapes (missing equations)
  • [ ] solve (don't forget gamma as well)
• magnetostatics
  • [ ] biot_savart
  • [ ] circuits
  • [ ] finite_element_2d
  • [ ] circular_arc
  • [ ] greens
  • [ ] polyhedral_prism
  • [ ] fem_utils
  • [ ] semianalytic_2d (only one equation (semianalytic_psi) missing)
  • [ ] tools
  • [ ] trapezoidal_prism
• fuel_cycle
  • [ ] lifecycle
  • [ ] timeline_tools
  • [ ] tools
• structural
  • [x] crosssection
  • [x] element (k arrays expressions shall be written out explicitly)
  • [ ] loads
  • [ ] matrixops (incomplete citation of k_condensation?)
  • [ ] model
  • [x] stress
  • [ ] symmetry (CyclicSymmetry needs equation/ further explanation)
  • [ ] transformation

^ This concludes the state of the equation documentation as of commit 38a4f9.

[athoynilimanew]

As of commit 0d6f36,

Added/amended docstrings for:

bluemira.geometry.coordinates :

• [x] vector_intersect()
• [x] get_bisection_line()
• [x] normal_vector()

bluemira.plasma_physics.collisions:

• [x] debye_length()
• [x] thermal_velocity()
• [x] reduced_mass()
• [x] de_broglie_length()
• [x] coulomb_logarithm()
• [x] impact_parameter_perp()

bluemira.structural.element:

• [x] _k_array()
• [x] local_k_shear()
• [x] local_k()

bluemira.balance_of_plant.calculations:

• [x] H2O_pumping()
• [x] superheated_rankine()

bluemira.magnetostatics.greens:

• [x] circular_coil_inductance_kirchhoff()
• [x] circular_coil_inductance_elliptic()

bluemira.magnetostatics.semianalytic_2d:

• [x] semianalytic_psi() [partially. Still need to implement full expression for psi]

bluemira.equilibria.coils._coil:

• [x] area()
• [x] volume()

[athoynilimanew]

As of commit [8c004bd2cecd9226fd98067b49ad5d61550578fb]

Added/amended docstrings for:

bluemira.geometry.tools :

• [x] signed_distance()
• [x] make_bspline()
• [x] make_bsplinesurface()
• [x] make_bezier()

bluemira.utilities.tools :

• [x] levi_civita_tensor()