added docstrings to controls and project fields

Author: alexhroom

RATapi/controls.py

@@ -6,6 +6,7 @@
 import prettytable
 from pydantic import (
     BaseModel,
+    ConfigDict,
     Field,
     ValidationError,
     ValidatorFunctionWrapHandler,
@@ -38,41 +39,70 @@
 
 class Controls(BaseModel, validate_assignment=True, extra="forbid"):
     """The full set of controls parameters for all five procedures that are required for the compiled RAT code."""
+    model_config = ConfigDict(use_attribute_docstrings=True)
 
     # All Procedures
     procedure: Procedures = Procedures.Calculate
+    """Which procedure RAT should execute. Can be 'calculate', 'simplex', 'de', 'ns', or 'dream'."""
     parallel: Parallel = Parallel.Single
+    """How the calculation should be parallelised. Can be 'single', 'contrasts' or 'points'."""
     calcSldDuringFit: bool = False
+    """Whether SLD will be calculated during fit (for live plotting etc.)"""
     resampleMinAngle: float = Field(0.9, le=1, gt=0)
+    """The upper threshold on the angle between three sampled points for resampling, in radians over pi."""
     resampleNPoints: int = Field(50, gt=0)
+    """The number of initial points to use for resampling."""
     display: Display = Display.Iter
+    """How much RAT should print to the terminal. Can be 'off', 'iter', 'notify', or 'final'."""
     # Simplex
     xTolerance: float = Field(1.0e-6, gt=0.0)
+    """The termination tolerance for step size."""
     funcTolerance: float = Field(1.0e-6, gt=0.0)
+    """The termination tolerance for change in chi-squared."""
     maxFuncEvals: int = Field(10000, gt=0)
+    """The maximum number of function evaluations before the algorithm terminates."""
     maxIterations: int = Field(1000, gt=0)
+    """The maximum number of iterations before the algorithm terminates."""
     # Simplex and DE
     updateFreq: int = 1
+    """How often to print out progress to the terminal, in iterations."""
     updatePlotFreq: int = 20
+    """How often the live plot should be updated if using."""
     # DE
     populationSize: int = Field(20, ge=1)
+    """The number of candidate solutions that exist at any time."""
     fWeight: float = 0.5
+    """The step size for how different mutations are to their parents."""
     crossoverProbability: float = Field(0.8, gt=0.0, lt=1.0)
+    """The probability of exchange of parameters between individuals at any iteration."""
     strategy: Strategies = Strategies.RandomWithPerVectorDither
+    """The algorithm used to generate new candidates."""
     targetValue: float = Field(1.0, ge=1.0)
+    """The value of chi-squared at which the algorithm will terminate."""
     numGenerations: int = Field(500, ge=1)
+    """The maximum number of iterations before the algorithm terminates."""
     # NS
     nLive: int = Field(150, ge=1)
+    """The number of points to sample."""
     nMCMC: int = Field(0, ge=0)
+    """If non-zero, an MCMC process with ``nMCMC`` chains will be used instead of MultiNest."""
     propScale: float = Field(0.1, gt=0.0, lt=1.0)
+    """A scaling factor for the ellipsoid generated by MultiNest."""
     nsTolerance: float = Field(0.1, ge=0.0)
+    """The tolerance threshold for when the algorithm should terminate."""
     # Dream
     nSamples: int = Field(20000, ge=0)
+    """The number of samples in the initial population for each chain."""
     nChains: int = Field(10, gt=0)
+    """The number of Markov chains to use in the algorithm."""
     jumpProbability: float = Field(0.5, gt=0.0, lt=1.0)
+    """The probability range for the size of jumps in sampling. Larger values mean more variable jumps."""
     pUnitGamma: float = Field(0.2, gt=0.0, lt=1.0)
+    """The probability that the scaling-down factor of jumps will be ignored and a larger jump will be taken."""
     boundHandling: BoundHandling = BoundHandling.Reflect
+    """How steps across the boundary of the space should be handled. Can be 'off', 'reflect', 'bound', or 'fold'."""
     adaptPCR: bool = True
+    """Whether the crossover probability for differential evolution should be adapted by the algorithm as it runs."""
     # Private field for IPC file
     _IPCFilePath: str = ""
 

RATapi/project.py

@@ -11,6 +11,7 @@
 import numpy as np
 from pydantic import (
     BaseModel,
+    ConfigDict,
     Discriminator,
     Field,
     Tag,
@@ -129,14 +130,21 @@ class Project(BaseModel, validate_assignment=True, extra="forbid"):
     This class combines the data defined in each of the pydantic models included in "models.py" into the full set of
     inputs required for a reflectivity calculation.
     """
+    model_config = ConfigDict(use_attribute_docstrings=True)
 
     name: str = ""
+    """The name of the project."""
     calculation: Calculations = Calculations.Normal
+    """What calculation type should be used. Can be 'normal' or 'domains'."""
     model: LayerModels = LayerModels.StandardLayers
+    """What layer model should be used. Can be 'standard layers', 'custom layers', or 'custom xy'."""
     geometry: Geometries = Geometries.AirSubstrate
+    """What geometry should be used. Can be 'air/substrate' or 'substrate/liquid'"""
     absorption: bool = False
+    """Whether imaginary (absorption) SLD should be accounted for."""
 
     parameters: ClassList[RATapi.models.Parameter] = ClassList()
+    """The list of parameters used in the layers of a model."""
 
     bulk_in: ClassList[RATapi.models.Parameter] = ClassList(
         RATapi.models.Parameter(
@@ -150,6 +158,7 @@ class Project(BaseModel, validate_assignment=True, extra="forbid"):
             sigma=np.inf,
         ),
     )
+    """The parameters for SLD of the entry interfaces of a model.""" 
 
     bulk_out: ClassList[RATapi.models.Parameter] = ClassList(
         RATapi.models.Parameter(
@@ -163,6 +172,7 @@ class Project(BaseModel, validate_assignment=True, extra="forbid"):
             sigma=np.inf,
         ),
     )
+    """The parameters for SLD of the exit interfaces of a model."""
 
     scalefactors: ClassList[RATapi.models.Parameter] = ClassList(
         RATapi.models.Parameter(
@@ -176,6 +186,7 @@ class Project(BaseModel, validate_assignment=True, extra="forbid"):
             sigma=np.inf,
         ),
     )
+    """The parameters for scale factors to handle systematic error in model data."""
 
     domain_ratios: ClassList[RATapi.models.Parameter] = ClassList(
         RATapi.models.Parameter(
@@ -189,6 +200,7 @@ class Project(BaseModel, validate_assignment=True, extra="forbid"):
             sigma=np.inf,
         ),
     )
+    """The parameters for weighting between domains of a domains model."""
 
     background_parameters: ClassList[RATapi.models.Parameter] = ClassList(
         RATapi.models.Parameter(
@@ -202,10 +214,12 @@ class Project(BaseModel, validate_assignment=True, extra="forbid"):
             sigma=np.inf,
         ),
     )
+    """The parameters for models of backgrounds."""
 
     backgrounds: ClassList[RATapi.models.Background] = ClassList(
         RATapi.models.Background(name="Background 1", type=TypeOptions.Constant, source="Background Param 1"),
     )
+    """The models for background noise in the project."""
 
     resolution_parameters: ClassList[RATapi.models.Parameter] = ClassList(
         RATapi.models.Parameter(
@@ -219,13 +233,17 @@ class Project(BaseModel, validate_assignment=True, extra="forbid"):
             sigma=np.inf,
         ),
     )
+    """The parameters for models of resolutions."""
 
     resolutions: ClassList[RATapi.models.Resolution] = ClassList(
         RATapi.models.Resolution(name="Resolution 1", type=TypeOptions.Constant, source="Resolution Param 1"),
     )
+    """The models for instrument resolution in the project."""
 
     custom_files: ClassList[RATapi.models.CustomFile] = ClassList()
+    """Handles for custom files used by the project."""
     data: ClassList[RATapi.models.Data] = ClassList()
+    """Arrays of experimental data corresponding to a model."""
     layers: Union[
         Annotated[ClassList[RATapi.models.Layer], Tag("no_abs")],
         Annotated[ClassList[RATapi.models.AbsorptionLayer], Tag("abs")],
@@ -238,7 +256,9 @@ class Project(BaseModel, validate_assignment=True, extra="forbid"):
             custom_error_context={"discriminator": "absorption_or_no"},
         ),
     )
+    """The layers of a standard layer model."""
     domain_contrasts: ClassList[RATapi.models.DomainContrast] = ClassList()
+    """The groups of layers required by each domain in a domains model."""
     contrasts: Union[
         Annotated[ClassList[RATapi.models.Contrast], Tag("no_ratio")],
         Annotated[ClassList[RATapi.models.ContrastWithRatio], Tag("ratio")],
@@ -251,6 +271,7 @@ class Project(BaseModel, validate_assignment=True, extra="forbid"):
             custom_error_context={"discriminator": "ratio_or_no_ratio"},
         ),
     )
+    """All groups of components used to define each model in the project."""
 
     _all_names: dict
     _contrast_model_field: str