Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for default grid and target/bounds for objectives #988

Merged
merged 4 commits into from
Apr 9, 2024
Merged

Add documentation for default grid and target/bounds for objectives #988

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9cc5754
Add documentation for default target/bounds for objectives
f0uriest Apr 5, 2024
a5fd6dd
Add documentation for default grids
f0uriest Apr 5, 2024
f9056bd
Merge branch 'master' into rc/document_target_grid
f0uriest Apr 6, 2024
06fe6c9
fix typo in docstring
dpanici Apr 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions desc/objectives/_bootstrap.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,11 @@ class BootstrapRedlConsistency(_Objective):
Equilibrium that will be optimized to satisfy the Objective.
target : {float, ndarray}, optional
Target value(s) of the objective. Only used if bounds is None.
Must be broadcastable to Objective.dim_f.
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple of {float, ndarray}, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : {float, ndarray}, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -57,6 +58,7 @@ class BootstrapRedlConsistency(_Objective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``LinearGrid(eq.L_grid, eq.M_grid, eq.N_grid)``
helicity : tuple, optional
Type of quasi-symmetry (M, N). Default = quasi-axisymmetry (1, 0).
First entry must be M=1. Second entry is the toroidal mode number N,
Expand Down
18 changes: 12 additions & 6 deletions desc/objectives/_coils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -255,10 +255,11 @@ class CoilLength(_CoilObjective):
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.
be flattened according to the number of inputs. Defaults to ``target=2*np.pi``.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this default depend on the diameter of the coil. What if the minor radius of the last surface is 10 ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could maybe try to make better default values, but it should be in another PR. This one is just about documenting what is currently there.

bounds : tuple of float, ndarray, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=2*np.pi``.
weight : float, ndarray, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -280,6 +281,7 @@ class CoilLength(_CoilObjective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``LinearGrid(N=2 * coil.N + 5)``
name : str, optional
Name of the objective function.
"""
Expand Down Expand Up @@ -385,10 +387,11 @@ class CoilCurvature(_CoilObjective):
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.
be flattened according to the number of inputs. Defaults to ``bounds=(0,1)``.
bounds : tuple of float, ndarray, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``bounds=(0,1)``.
weight : float, ndarray, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -410,6 +413,7 @@ class CoilCurvature(_CoilObjective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``LinearGrid(N=2 * coil.N + 5)``
name : str, optional
Name of the objective function.
"""
Expand Down Expand Up @@ -500,10 +504,11 @@ class CoilTorsion(_CoilObjective):
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.
be flattened according to the number of inputs. Defaults to ``target=0``.
bounds : tuple of float, ndarray, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : float, ndarray, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -525,6 +530,7 @@ class CoilTorsion(_CoilObjective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``LinearGrid(N=2 * coil.N + 5)``
name : str, optional
Name of the objective function.
"""
Expand Down
43 changes: 25 additions & 18 deletions desc/objectives/_equilibrium.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,11 @@ class ForceBalance(_Objective):
Equilibrium that will be optimized to satisfy the Objective.
target : {float, ndarray}, optional
Target value(s) of the objective. Only used if bounds is None.
Must be broadcastable to Objective.dim_f.
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple of {float, ndarray}, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : {float, ndarray}, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -59,6 +60,7 @@ class ForceBalance(_Objective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``ConcentricGrid(eq.L_grid, eq.M_grid, eq.N_grid)``
name : str, optional
Name of the objective function.

Expand Down Expand Up @@ -209,13 +211,14 @@ class ForceBalanceAnisotropic(_Objective):
Equilibrium that will be optimized to satisfy the Objective.
target : float, ndarray, optional
Target value(s) of the objective.
len(target) must be equal to Objective.dim_f
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple, optional
Lower and upper bounds on the objective. Overrides target.
len(bounds[0]) and len(bounds[1]) must be equal to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : float, ndarray, optional
Weighting to apply to the Objective, relative to other Objectives.
len(weight) must be equal to Objective.dim_f
Must be broadcastable to Objective.dim_f.
normalize : bool
Whether to compute the error in physical units or non-dimensionalize.
normalize_target : bool
Expand All @@ -229,11 +232,7 @@ class ForceBalanceAnisotropic(_Objective):
normalization.
grid : Grid, ndarray, optional
Collocation grid containing the nodes to evaluate at.
deriv_mode : {"auto", "fwd", "rev"}
Specify how to compute jacobian matrix, either forward mode or reverse mode AD.
"auto" selects forward or reverse mode based on the size of the input and output
of the objective. Has no effect on self.grad or self.hess which always use
reverse mode and forward over reverse mode respectively.
Defaults to ``ConcentricGrid(eq.L_grid, eq.M_grid, eq.N_grid)``
name : str
Name of the objective function.

Expand Down Expand Up @@ -366,10 +365,11 @@ class RadialForceBalance(_Objective):
Equilibrium that will be optimized to satisfy the Objective.
target : {float, ndarray}, optional
Target value(s) of the objective. Only used if bounds is None.
Must be broadcastable to Objective.dim_f.
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple of {float, ndarray}, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : {float, ndarray}, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -390,6 +390,7 @@ class RadialForceBalance(_Objective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``ConcentricGrid(eq.L_grid, eq.M_grid, eq.N_grid)``
name : str, optional
Name of the objective function.

Expand Down Expand Up @@ -522,10 +523,11 @@ class HelicalForceBalance(_Objective):
Equilibrium that will be optimized to satisfy the Objective.
target : {float, ndarray}, optional
Target value(s) of the objective. Only used if bounds is None.
Must be broadcastable to Objective.dim_f.
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple of {float, ndarray}, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : {float, ndarray}, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -546,6 +548,7 @@ class HelicalForceBalance(_Objective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``ConcentricGrid(eq.L_grid, eq.M_grid, eq.N_grid)``
name : str, optional
Name of the objective function.

Expand Down Expand Up @@ -674,10 +677,11 @@ class Energy(_Objective):
Equilibrium that will be optimized to satisfy the Objective.
target : {float, ndarray}, optional
Target value(s) of the objective. Only used if bounds is None.
Must be broadcastable to Objective.dim_f.
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple of {float, ndarray}, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : {float, ndarray}, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -698,6 +702,7 @@ class Energy(_Objective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``QuadratureGrid(eq.L_grid, eq.M_grid, eq.N_grid)``
gamma : float, optional
Adiabatic (compressional) index. Default = 0.
name : str, optional
Expand Down Expand Up @@ -841,10 +846,11 @@ class CurrentDensity(_Objective):
Equilibrium that will be optimized to satisfy the Objective.
target : {float, ndarray}, optional
Target value(s) of the objective. Only used if bounds is None.
Must be broadcastable to Objective.dim_f.
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple of {float, ndarray}, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : {float, ndarray}, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -865,6 +871,7 @@ class CurrentDensity(_Objective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``ConcentricGrid(eq.L_grid, eq.M_grid, eq.N_grid)``
name : str, optional
Name of the objective function.

Expand Down
27 changes: 16 additions & 11 deletions desc/objectives/_free_boundary.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,13 +44,14 @@ class VacuumBoundaryError(_Objective):
External field produced by coils or other sources outside the plasma.
target : float, ndarray, optional
Target value(s) of the objective. Only used if bounds is None.
len(target) must be equal to Objective.dim_f
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple, optional
Lower and upper bounds on the objective. Overrides target.
len(bounds[0]) and len(bounds[1]) must be equal to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : float, ndarray, optional
Weighting to apply to the Objective, relative to other Objectives.
len(weight) must be equal to Objective.dim_f
Must be broadcastable to Objective.dim_f.
normalize : bool
Whether to compute the error in physical units or non-dimensionalize.
normalize_target : bool
Expand All @@ -68,8 +69,9 @@ class VacuumBoundaryError(_Objective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate error at. Should be at rho=1.
Defaults to ``Linear(M=eq.M_grid, N=eq.N_grid)``
dpanici marked this conversation as resolved.
Show resolved Hide resolved
field_grid : Grid, optional
Grid used to discretize field.
Grid used to discretize field. Defaults to the default grid for given field.
field_fixed : bool
Whether to assume the field is fixed. For free boundary solve, should
be fixed. For single stage optimization, should be False (default).
Expand Down Expand Up @@ -352,13 +354,14 @@ class BoundaryError(_Objective):
External field produced by coils.
target : float, ndarray, optional
Target value(s) of the objective. Only used if bounds is None.
len(target) must be equal to Objective.dim_f
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple, optional
Lower and upper bounds on the objective. Overrides target.
len(bounds[0]) and len(bounds[1]) must be equal to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : float, ndarray, optional
Weighting to apply to the Objective, relative to other Objectives.
len(weight) must be equal to Objective.dim_f
Must be broadcastable to Objective.dim_f.
normalize : bool
Whether to compute the error in physical units or non-dimensionalize.
normalize_target : bool
Expand All @@ -382,8 +385,9 @@ class BoundaryError(_Objective):
Collocation grid containing the nodes to evaluate at for source terms for Biot-
Savart integral and where to evaluate errors. source_grid should not be
stellarator symmetric, and both should be at rho=1.
Defaults to ``Linear(M=eq.M_grid, N=eq.N_grid)`` for both.
dpanici marked this conversation as resolved.
Show resolved Hide resolved
field_grid : Grid, optional
Grid used to discretize field.
Grid used to discretize field. Defaults to default grid for given field.
field_fixed : bool
Whether to assume the field is fixed. For free boundary solve, should
be fixed. For single stage optimization, should be False (default).
Expand Down Expand Up @@ -801,13 +805,14 @@ class BoundaryErrorNESTOR(_Objective):
External field produced by coils.
target : float, ndarray, optional
Target value(s) of the objective. Only used if bounds is None.
len(target) must be equal to Objective.dim_f
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple, optional
Lower and upper bounds on the objective. Overrides target.
len(bounds[0]) and len(bounds[1]) must be equal to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : float, ndarray, optional
Weighting to apply to the Objective, relative to other Objectives.
len(weight) must be equal to Objective.dim_f
Must be broadcastable to Objective.dim_f.
mf, nf : integer
maximum poloidal and toroidal mode numbers to use for NESTOR scalar potential.
ntheta, nzeta : int
Expand Down
19 changes: 12 additions & 7 deletions desc/objectives/_generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,14 @@ class GenericObjective(_Objective):
Equilibrium that will be optimized to satisfy the Objective.
target : {float, ndarray}, optional
Target value(s) of the objective. Only used if bounds is None.
Must be broadcastable to Objective.dim_f.
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple of {float, ndarray}, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : {float, ndarray}, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Must be broadcastable to to Objective.dim_f.
normalize : bool, optional
Whether to compute the error in physical units or non-dimensionalize.
Has no effect for this objective
Expand All @@ -51,6 +52,7 @@ class GenericObjective(_Objective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``QuadratureGrid(eq.L_grid, eq.M_grid, eq.N_grid)``.
name : str, optional
Name of the objective function.

Expand Down Expand Up @@ -181,10 +183,11 @@ class LinearObjectiveFromUser(_FixedObjective):
Object whose degrees of freedom are being constrained.
target : dict of {float, ndarray}, optional
Target value(s) of the objective. Only used if bounds is None.
Should have the same tree structure as thing.params. Defaults to things.params.
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple of dict {float, ndarray}, optional
Lower and upper bounds on the objective. Overrides target.
Should have the same tree structure as thing.params.
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : dict of {float, ndarray}, optional
Weighting to apply to the Objective, relative to other Objectives.
Should be a scalar or have the same tree structure as thing.params.
Expand Down Expand Up @@ -303,10 +306,11 @@ class ObjectiveFromUser(_Objective):
Equilibrium that will be optimized to satisfy the Objective.
target : {float, ndarray}, optional
Target value(s) of the objective. Only used if bounds is None.
Must be broadcastable to Objective.dim_f.
Must be broadcastable to Objective.dim_f. Defaults to ``target=0``.
bounds : tuple of {float, ndarray}, optional
Lower and upper bounds on the objective. Overrides target.
Both bounds must be broadcastable to to Objective.dim_f
Both bounds must be broadcastable to to Objective.dim_f.
Defaults to ``target=0``.
weight : {float, ndarray}, optional
Weighting to apply to the Objective, relative to other Objectives.
Must be broadcastable to to Objective.dim_f
Expand All @@ -328,6 +332,7 @@ class ObjectiveFromUser(_Objective):
reverse mode and forward over reverse mode respectively.
grid : Grid, optional
Collocation grid containing the nodes to evaluate at.
Defaults to ``QuadratureGrid(eq.L_grid, eq.M_grid, eq.N_grid)``.
name : str, optional
Name of the objective function.

Expand Down
Loading
Loading