From 72f256a06477f11ebeb7d26a9aadef0c7279ae67 Mon Sep 17 00:00:00 2001 From: YigitElma Date: Sat, 28 Sep 2024 14:24:58 -0400 Subject: [PATCH] make fixes for default values --- desc/objectives/_bootstrap.py | 4 +- desc/objectives/_coils.py | 81 ++++++++++++------------------- desc/objectives/_equilibrium.py | 24 ++++++--- desc/objectives/_free_boundary.py | 12 +++-- desc/objectives/_generic.py | 12 +++-- desc/objectives/_geometry.py | 47 +++++++++++++++--- desc/objectives/_omnigenity.py | 20 ++++++-- desc/objectives/_power_balance.py | 8 ++- desc/objectives/objective_funs.py | 53 +++++++++++++++++++- 9 files changed, 182 insertions(+), 79 deletions(-) diff --git a/desc/objectives/_bootstrap.py b/desc/objectives/_bootstrap.py index 966eedda2..9f6850cb2 100644 --- a/desc/objectives/_bootstrap.py +++ b/desc/objectives/_bootstrap.py @@ -42,7 +42,9 @@ class BootstrapRedlConsistency(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _coordinates = "r" _units = "(T A m^-2)" diff --git a/desc/objectives/_coils.py b/desc/objectives/_coils.py index 7b24adb15..d63f0bee3 100644 --- a/desc/objectives/_coils.py +++ b/desc/objectives/_coils.py @@ -35,16 +35,9 @@ class _CoilObjective(_Objective): """ - overwrite = { - "loss_function": """ - loss_function : {None, 'mean', 'min', 'max'}, optional - Loss function to apply to the objective values once computed. This loss - function is called on the raw compute value, before any shifting, - scaling, or normalization. Operates over all coils, not each individual - coil. - """, - } - __doc__ = __doc__.rstrip() + collect_docs(overwrite=overwrite) + __doc__ = __doc__.rstrip() + collect_docs( + coil=True, + ) def __init__( self, @@ -201,16 +194,6 @@ def compute(self, params, constants=None): return data -overwrite_coil_length = _CoilObjective.overwrite.copy() -overwrite_coil_length[ - "target" -] = """ - target : float, ndarray, optional - Target value(s) of the objective. Only used if bounds is None. - Must be broadcastable to Objective.dim_f. If array, it has to - be flattened according to the number of inputs. """ - - class CoilLength(_CoilObjective): """Coil length. @@ -224,11 +207,11 @@ class CoilLength(_CoilObjective): """ - overwrite = overwrite_coil_length.copy() - overwrite["target"] = ( - overwrite["target"].rstrip() + " Defaults to ``target=2*np.pi``.\n" + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=2*np.pi``.", + bounds_default="``target=2*np.pi``.", + coil=True, ) - __doc__ = __doc__.rstrip() + collect_docs(overwrite=overwrite) _scalar = False # Not always a scalar, if a coilset is passed in _units = "(m)" @@ -328,9 +311,11 @@ class CoilCurvature(_CoilObjective): """ - overwrite = overwrite_coil_length - overwrite["target"] = overwrite["target"].rstrip() + "\n" - __doc__ = __doc__.rstrip() + collect_docs(overwrite=overwrite) + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``bounds=(0,1).``", + bounds_default="``bounds=(0,1).``", + coil=True, + ) _scalar = False _units = "(m^-1)" @@ -425,9 +410,11 @@ class CoilTorsion(_CoilObjective): """ - overwrite = overwrite_coil_length.copy() - overwrite["target"] = overwrite["target"].rstrip() + " Defaults to ``target=0``.\n" - __doc__ = __doc__.rstrip() + collect_docs(overwrite=overwrite) + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", + bounds_default="``target=0``.", + coil=True, + ) _scalar = False _units = "(m^-1)" @@ -522,9 +509,11 @@ class CoilCurrentLength(CoilLength): """ - overwrite = overwrite_coil_length.copy() - overwrite["target"] = overwrite["target"].rstrip() + " Defaults to ``target=0``.\n" - __doc__ = __doc__.rstrip() + collect_docs(overwrite=overwrite) + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", + bounds_default="``target=0``.", + coil=True, + ) _scalar = False _units = "(A*m)" @@ -628,9 +617,7 @@ class CoilSetMinDistance(_Objective): """ - overwrite = overwrite_coil_length.copy() - overwrite["target"] = overwrite["target"].rstrip() + "\n" - __doc__ = __doc__.rstrip() + collect_docs(overwrite=overwrite) + __doc__ = __doc__.rstrip() + collect_docs(coil=True) _scalar = False _units = "(m)" @@ -780,8 +767,7 @@ class PlasmaCoilSetMinDistance(_Objective): """ - overwrite = {"loss_function": overwrite_coil_length["loss_function"]} - __doc__ = __doc__.rstrip() + collect_docs(overwrite=overwrite) + __doc__ = __doc__.rstrip() + collect_docs(coil=True) _scalar = False _units = "(m)" @@ -997,8 +983,11 @@ class QuadraticFlux(_Objective): """ - overwrite = {"loss_function": ""} - __doc__ = __doc__.rstrip() + collect_docs(overwrite=overwrite) + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", + bounds_default="``target=0``.", + loss_detail=" Note: has no effect for this objective.", + ) _scalar = False _linear = False @@ -1186,15 +1175,9 @@ class ToroidalFlux(_Objective): """ - overwrite = { - "loss_function": """ - loss_function : {None, 'mean', 'min', 'max'}, optional - Loss function to apply to the objective values once computed. This function - is called on the raw compute value, before any shifting, scaling, or - normalization. Note: has no effect for this objective. - """ - } - __doc__ = __doc__.rstrip() + collect_docs(overwrite=overwrite) + __doc__ = __doc__.rstrip() + collect_docs( + loss_detail=" Note: has no effect for this objective." + ) _coordinates = "rtz" _units = "(Wb)" diff --git a/desc/objectives/_equilibrium.py b/desc/objectives/_equilibrium.py index 68497b230..7be04509e 100644 --- a/desc/objectives/_equilibrium.py +++ b/desc/objectives/_equilibrium.py @@ -39,7 +39,9 @@ class ForceBalance(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _equilibrium = True _coordinates = "rtz" @@ -192,7 +194,9 @@ class ForceBalanceAnisotropic(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _units = "(N)" _coordinates = "rtz" @@ -327,7 +331,9 @@ class RadialForceBalance(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _equilibrium = True _coordinates = "rtz" @@ -462,7 +468,9 @@ class HelicalForceBalance(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _equilibrium = True _coordinates = "rtz" @@ -595,7 +603,9 @@ class Energy(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _scalar = True _coordinates = "" @@ -739,7 +749,9 @@ class CurrentDensity(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _equilibrium = True _coordinates = "rtz" diff --git a/desc/objectives/_free_boundary.py b/desc/objectives/_free_boundary.py index 7892da859..569a0611e 100644 --- a/desc/objectives/_free_boundary.py +++ b/desc/objectives/_free_boundary.py @@ -49,7 +49,9 @@ class VacuumBoundaryError(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _scalar = False _linear = False @@ -363,7 +365,9 @@ class BoundaryError(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) __doc__ += """ Examples -------- @@ -798,7 +802,9 @@ class BoundaryErrorNESTOR(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _scalar = False _linear = False diff --git a/desc/objectives/_generic.py b/desc/objectives/_generic.py index 07666fd99..8e16e61cf 100644 --- a/desc/objectives/_generic.py +++ b/desc/objectives/_generic.py @@ -32,7 +32,9 @@ class GenericObjective(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _print_value_fmt = "Generic objective value: " @@ -166,7 +168,9 @@ class LinearObjectiveFromUser(_FixedObjective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _scalar = False _linear = True @@ -278,7 +282,9 @@ class ObjectiveFromUser(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) __doc__ += """ Examples -------- diff --git a/desc/objectives/_geometry.py b/desc/objectives/_geometry.py index 1ba6c8426..ae6061395 100644 --- a/desc/objectives/_geometry.py +++ b/desc/objectives/_geometry.py @@ -28,7 +28,13 @@ class AspectRatio(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=2``.", + bounds_default="``target=2``.", + normalize_detail=" Note: Has no effect for this objective.", + normalize_target_detail=" Note: Has no effect for this objective.", + loss_detail=" Note: Has no effect for this objective.", + ) _scalar = True _units = "(dimensionless)" @@ -166,7 +172,13 @@ class Elongation(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=1``.", + bounds_default="``target=1``.", + normalize_detail=" Note: Has no effect for this objective.", + normalize_target_detail=" Note: Has no effect for this objective.", + loss_detail=" Note: Has no effect for this objective.", + ) _scalar = True _units = "(dimensionless)" @@ -303,7 +315,11 @@ class Volume(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=1``.", + bounds_default="``target=1``.", + loss_detail=" Note: Has no effect for this objective.", + ) _scalar = True _units = "(m^3)" @@ -490,7 +506,10 @@ class PlasmaVesselDistance(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``bounds=(1,np.inf)``.", + bounds_default="``bounds=(1,np.inf)``.", + ) _coordinates = "rtz" _units = "(m)" @@ -806,7 +825,10 @@ class MeanCurvature(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``bounds=(-np.inf,0)``.", + bounds_default="``bounds=(-np.inf,0)``.", + ) _coordinates = "rtz" _units = "(m^-1)" @@ -943,7 +965,10 @@ class PrincipalCurvature(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=1``.", + bounds_default="``target=1``.", + ) _coordinates = "rtz" _units = "(m^-1)" @@ -1075,7 +1100,10 @@ class BScaleLength(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``bounds=(1,np.inf)``.", + bounds_default="``bounds=(1,np.inf)``.", + ) _coordinates = "rtz" _units = "(m)" @@ -1203,7 +1231,10 @@ class GoodCoordinates(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", + bounds_default="``target=0``.", + ) _scalar = False _units = "(dimensionless)" diff --git a/desc/objectives/_omnigenity.py b/desc/objectives/_omnigenity.py index fbd0cbf47..e992a970d 100644 --- a/desc/objectives/_omnigenity.py +++ b/desc/objectives/_omnigenity.py @@ -33,7 +33,9 @@ class QuasisymmetryBoozer(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _units = "(T)" _print_value_fmt = "Quasi-symmetry Boozer error: " @@ -222,7 +224,9 @@ class QuasisymmetryTwoTerm(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _coordinates = "rtz" _units = "(T^3)" @@ -384,7 +388,9 @@ class QuasisymmetryTripleProduct(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _coordinates = "rtz" _units = "(T^4/m^2)" @@ -539,7 +545,9 @@ class Omnigenity(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _coordinates = "rtz" _units = "(T)" @@ -850,7 +858,9 @@ class Isodynamicity(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _coordinates = "rtz" _units = "(dimensionless)" diff --git a/desc/objectives/_power_balance.py b/desc/objectives/_power_balance.py index c4f01dc7c..e72bcb5f1 100644 --- a/desc/objectives/_power_balance.py +++ b/desc/objectives/_power_balance.py @@ -32,7 +32,9 @@ class FusionPower(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=1e9``.", bounds_default="``target=1e9``." + ) _scalar = True _units = "(W)" @@ -194,7 +196,9 @@ class HeatingPowerISS04(_Objective): """ - __doc__ = __doc__.rstrip() + collect_docs() + __doc__ = __doc__.rstrip() + collect_docs( + target_default="``target=0``.", bounds_default="``target=0``." + ) _scalar = True _units = "(W)" diff --git a/desc/objectives/objective_funs.py b/desc/objectives/objective_funs.py index 9eba5f503..b8d23769c 100644 --- a/desc/objectives/objective_funs.py +++ b/desc/objectives/objective_funs.py @@ -99,7 +99,15 @@ } -def collect_docs(overwrite=None): +def collect_docs( + overwrite=None, + target_default="", + bounds_default="", + normalize_detail=None, + normalize_target_detail=None, + loss_detail=None, + coil=False, +): """Collect default parameters for the docstring of Objective. Parameters @@ -109,6 +117,19 @@ def collect_docs(overwrite=None): all default parameters are included as they are. Use this argument if you want to specify a special docstring for a specific parameter in your objective definition. + target_default : str, optional + Default value for the target parameter. + bounds_default : str, optional + Default value for the bounds parameter. + normalize_detail : str, optional + Additional information about the normalize parameter. + normalize_target_detail : str, optional + Additional information about the normalize_target parameter. + loss_detail : str, optional + Additional information about the loss function. + coil : bool, optional + Whether the objective is a coil objective. If True, adds extra docs to + target and loss_function. Returns ------- @@ -121,7 +142,35 @@ def collect_docs(overwrite=None): if overwrite is not None and key in overwrite.keys(): doc_params += overwrite[key].rstrip() else: - doc_params += docs[key].rstrip() + if key == "target": + target = "" + if coil: + target += "If array, it has to be flattened according to the " + +"number of inputs." + if target_default != "": + target += " Defaults to " + target_default + doc_params += docs[key].rstrip() + target + elif key == "bounds" and bounds_default != "": + doc_params += docs[key].rstrip() + " Defaults to " + bounds_default + elif key == "loss_function": + loss = "" + if coil: + loss = " Operates over all coils, not each individual coil." + if loss_detail is not None: + loss += loss_detail + doc_params += docs[key].rstrip() + loss + elif key == "normalize": + norm = "" + if normalize_detail is not None: + norm += normalize_detail + doc_params += docs[key].rstrip() + norm + elif key == "normalize_target": + norm_target = "" + if normalize_target_detail is not None: + norm_target = normalize_target_detail + doc_params += docs[key].rstrip() + norm_target + else: + doc_params += docs[key].rstrip() return doc_params