API design added

Signed-off-by: Shashank Mittal <[email protected]>
kubeflow · Jul 4, 2024 · 1492ebf · 1492ebf
1 parent d853fa5
commit 1492ebf
Showing 1 changed file with 88 additions and 2 deletions.
diff --git a/docs/proposals/parameter-distribution.md b/docs/proposals/parameter-distribution.md
@@ -25,10 +25,10 @@ A Data Scientist requires Katib to support multiple hyperparameter distributions
 |-------------------------------|-----------------------|--------------------------------------|-----------------------|
 | **Uniform Continuous**        | `hp.uniform`          | `FloatDistribution`                  | `tune.uniform`        |
 | **Quantized Uniform**         | `hp.quniform`         | `DiscreteUniformDistribution`(deprecated)  Use `FloatDistribution` instead. | `tune.quniform`       |
-| **Log Uniform**               | `hp.loguniform`       | `LogUniformDistribution`(deprecated)  Use `FloatDistribution` instead. | `tune.loguniform`     |
+| **Log Uniform**               | `hp.loguniform`       | `LogUniformDistribution`(deprecated)  Use `FloatDistribution` instead with `log` boolean. | `tune.loguniform`     |
 | **Uniform Integer**           | `hp.randint` or quantized distributions with step size `q` set to 1 | `IntDistribution`                    | `tune.randint`        |
 | **Categorical**               | `hp.choice`           | `CategoricalDistribution`            | `tune.choice`         |
-| **Quantized Log Uniform**     | `hp.qloguniform`      | Custom Implementation Use `FloatDistribution` instead.                 | `tune.qloguniform`    |
+| **Quantized Log Uniform**     | `hp.qloguniform`      | Custom Implementation Use `FloatDistribution` instead with `log` boolean step must be `None` if log is true.                 | `tune.qloguniform`    |
 | **Normal**                    | `hp.normal`           | (Not directly supported)             | `tune.randn`          |
 | **Quantized Normal**          | `hp.qnormal`          | (Not directly supported)             | `tune.qrandn`         |
 | **Log Normal**                | `hp.lognormal`        | (Not directly supported)             | (Use custom transformation in `tune.randn`) |
@@ -38,6 +38,7 @@ A Data Scientist requires Katib to support multiple hyperparameter distributions
 
 ### How is Nevergrad implementing Hyperopt?
 Nevergrad maps parameter types (like p.Scalar, p.Log, p.Choice, etc.) from Nevergrad to corresponding Hyperopt search space definitions (hp.uniform, hp.loguniform, hp.choice, etc.).
+ref: https://github.com/facebookresearch/nevergrad/blob/c23f20406d9223afbe253f9807ca7e8ba993a1ac/nevergrad/optimization/externalbo.py#L47
 ```python
 def _get_search_space(param_name, param):
     if isinstance(param, p.Scalar):
@@ -52,6 +53,91 @@ def _get_search_space(param_name, param):
 ```
 The `_get_search_space` function constructs a search space that represents the entire parameter space defined by Nevergrad. 
 
+## API Design
+- [Distribution](#api-v1-beta1-Distribution)
+- [ExperimentSpec](#api-v1-beta1-ExperimentSpec)
+
+<a name="api-v1-beta1-ExperimentSpec"></a>
+
+### ExperimentSpec
+Specification of an Experiment. Experiment represents a single optimization run over a feasible space. 
+Each Experiment contains a configuration describing the feasible space, as well as a set of Trials.
+It is assumed that objective function f(x) does not change in the course of an Experiment.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| parameter_specs | [ExperimentSpec.ParameterSpecs](#api-v1-beta1-ExperimentSpec-ParameterSpecs) |  |  |
+| distribution | [ExperimentSpec.Distribution](#api-v1-beta1-ExperimentSpec-Distribution) |  |  |
+| objective | [ObjectiveSpec](#api-v1-beta1-ObjectiveSpec) |  | Objective specification for the Experiment. |
+| algorithm | [AlgorithmSpec](#api-v1-beta1-AlgorithmSpec) |  | HP or NAS algorithm specification for the Experiment. |
+| early_stopping | [EarlyStoppingSpec](#api-v1-beta1-EarlyStoppingSpec) |  | Early stopping specification for the Experiment. |
+| parallel_trial_count | [int32](#int32) |  | How many Trials can be processed in parallel. |
+| max_trial_count | [int32](#int32) |  | Max completed Trials to mark Experiment as succeeded. |
+| nas_config | [NasConfig](#api-v1-beta1-NasConfig) |  | NAS configuration for the Experiment. |
+
+<a name="api-v1-beta1-ExperimentSpec-Distribution"></a>
+
+### ExperimentSpec.Distribution
+List of Distribution.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| distributions | [Distribution](#api-v1-beta1-Distribution) | repeated |  |
+
+<a name="api-v1-beta1-Distribution"></a>
+
+### Distribution
+Config for a hyperparameter.
+Katib will create each Hyper parameter from this config.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| name | [string](#string) |  | Name of the Distribution. |
+| distribution_type | [DistributionType](#api-v1-beta1-DistributionType) |  | Type of the Distribution. |
+| feasible_space | [FeasibleSpace](#api-v1-beta1-FeasibleSpace) |  | FeasibleSpace for the Distribution. |
+
+<a name="api-v1-beta1-DistributionType"></a>
+
+### DistributionType
+Types of value for HyperParameter Distributions.
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| UNIFORM | 0 | Continuous uniform distribution. Samples values evenly between a minimum and maximum value. Use &#34;Max/Min&#34;. Use &#34;Step&#34; for `q`. |
+| LOGUNIFORM | 1 | Samples values such that their logarithm is uniformly distributed. Use &#34;Max/Min&#34;. Use &#34;Step&#34; for `q`. |
+| NORMAL | 2 | Normal (Gaussian) distribution type. Samples values according to a normal distribution characterized by a mean and standard deviation. Use &#34;Max/Min&#34;. Use &#34;Step&#34; for `q`. |
+| LOGNORMAL | 3 | Log-normal distribution type. Samples values such that their logarithm is normally distributed. Use &#34;Max/Min&#34;. Use &#34;Step&#34; for `q`. |
+| CATEGORICAL | 4 | Categorical type. Use &#34;List&#34; as string. |
+
+
+const (
+ 	CategoricalDistribution     Distribution = "categorical"
+ 	UniformDistribution         Distribution = "uniform"
+ 	LogUniformDistribution      Distribution = "logUniform"
+    NormalDistribution          Distribution = "normal"
+    LogNormalDistribution       Distribution = "logNormal"
+)
+
+<a name="api-v1-beta1-FeasibleSpace"></a>
+
+### FeasibleSpace
+Feasible space for optimization.
+Int and Double type use Max/Min.
+Discrete and Categorical type use List.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| max | [string](#string) |  | Max Value |
+| min | [string](#string) |  | Minimum Value |
+| list | [string](#string) | repeated | List of Values. |
+| step | [string](#string) |  | Step for double or int parameter or q for quantization|
+
+
+
 ## Experiment API changes
 Scope: `pkg/apis/controller/experiments/v1beta1/experiment_types.go`
 - Adding new field `Distribution` to `ParameterSpec`