Specify MaxNumberOfIterations for SDCA, K-Means (#2883)

Author: rogancarr

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/StochasticDualCoordinateAscentWithOptions.cs

@@ -27,7 +27,7 @@ public static void Example()
                 // Make the convergence tolerance tighter.
                 ConvergenceTolerance = 0.05f,
                 // Increase the maximum number of passes over training data.
-                NumberOfIterations = 30,
+                MaximumNumberOfIterations = 30,
                 // Give the instances of the positive class slightly more weight.
                 PositiveInstanceWeight = 1.2f,
             };

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Clustering/KMeans.cs

@@ -27,7 +27,7 @@ public static void Example()
             // A pipeline for concatenating the age, parity and induced columns together in the Features column and training a KMeans model on them.
             string outputColumnName = "Features";
             var pipeline = ml.Transforms.Concatenate(outputColumnName, new[] { "Age", "Parity", "Induced" })
-                .Append(ml.Clustering.Trainers.KMeans(outputColumnName, clustersCount: 2));
+                .Append(ml.Clustering.Trainers.KMeans(outputColumnName, numberOfClusters: 2));
 
             var model = pipeline.Fit(trainData);
 

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Clustering/KMeansWithOptions.cs

@@ -33,7 +33,7 @@ public static void Example()
                     {
                         FeatureColumnName = outputColumnName,
                         NumberOfClusters = 2,
-                        NumberOfIterations = 100,
+                        MaximumNumberOfIterations = 100,
                         OptimizationTolerance = 1e-6f,
                         NumberOfThreads = 1
                     }

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/MulticlassClassification/StochasticDualCoordinateAscentWithOptions.cs

@@ -33,7 +33,7 @@ public static void Example()
                 // Make the convergence tolerance tighter.
                 ConvergenceTolerance = 0.05f,
                 // Increase the maximum number of passes over training data.
-                NumberOfIterations = 30,
+                MaximumNumberOfIterations = 30,
             };
 
             // Create a pipeline. 

docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/Regression/StochasticDualCoordinateAscentWithOptions.cs

@@ -26,7 +26,7 @@ public static void Example()
                 // Make the convergence tolerance tighter.
                 ConvergenceTolerance = 0.02f,
                 // Increase the maximum number of passes over training data.
-                NumberOfIterations = 30,
+                MaximumNumberOfIterations = 30,
                 // Increase learning rate for bias
                 BiasLearningRate = 0.1f
             };

src/Microsoft.ML.KMeansClustering/KMeansCatalog.cs

@@ -19,7 +19,7 @@ public static class KMeansClusteringExtensions
         /// <param name="catalog">The clustering catalog trainer object.</param>
         /// <param name="featureColumnName">The name of the feature column.</param>
         /// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
-        /// <param name="clustersCount">The number of clusters to use for KMeans.</param>
+        /// <param name="numberOfClusters">The number of clusters to use for KMeans.</param>
         /// <example>
         /// <format type="text/markdown">
         /// <![CDATA[
@@ -29,7 +29,7 @@ public static class KMeansClusteringExtensions
         public static KMeansPlusPlusTrainer KMeans(this ClusteringCatalog.ClusteringTrainers catalog,
            string featureColumnName = DefaultColumnNames.Features,
            string exampleWeightColumnName = null,
-           int clustersCount = KMeansPlusPlusTrainer.Defaults.NumberOfClusters)
+           int numberOfClusters = KMeansPlusPlusTrainer.Defaults.NumberOfClusters)
         {
             Contracts.CheckValue(catalog, nameof(catalog));
             var env = CatalogUtils.GetEnvironment(catalog);
@@ -38,7 +38,7 @@ public static KMeansPlusPlusTrainer KMeans(this ClusteringCatalog.ClusteringTrai
             {
                 FeatureColumnName = featureColumnName,
                 ExampleWeightColumnName = exampleWeightColumnName,
-                NumberOfClusters = clustersCount
+                NumberOfClusters = numberOfClusters
             };
             return new KMeansPlusPlusTrainer(env, options);
         }

src/Microsoft.ML.KMeansClustering/KMeansPlusPlusTrainer.cs

@@ -80,7 +80,7 @@ public sealed class Options : UnsupervisedTrainerInputBaseWithWeight
             /// </summary>
             [Argument(ArgumentType.AtMostOnce, HelpText = "Maximum number of iterations.", ShortName = "maxiter")]
             [TGUI(Label = "Max Number of Iterations")]
-            public int NumberOfIterations = 1000;
+            public int MaximumNumberOfIterations = 1000;
 
             /// <summary>
             /// Memory budget (in MBs) to use for KMeans acceleration.
@@ -126,8 +126,8 @@ internal KMeansPlusPlusTrainer(IHostEnvironment env, Options options)
 
             _k = options.NumberOfClusters;
 
-            Host.CheckUserArg(options.NumberOfIterations > 0, nameof(options.NumberOfIterations), "Must be positive");
-            _maxIterations = options.NumberOfIterations;
+            Host.CheckUserArg(options.MaximumNumberOfIterations > 0, nameof(options.MaximumNumberOfIterations), "Must be positive");
+            _maxIterations = options.MaximumNumberOfIterations;
 
             Host.CheckUserArg(options.OptimizationTolerance > 0, nameof(options.OptimizationTolerance), "Tolerance must be positive");
             _convergenceThreshold = options.OptimizationTolerance;

src/Microsoft.ML.StandardLearners/Standard/SdcaBinary.cs

@@ -201,7 +201,7 @@ public abstract class OptionsBase : TrainerInputBaseWithLabel
             [Argument(ArgumentType.AtMostOnce, HelpText = "Maximum number of iterations; set to 1 to simulate online learning. Defaults to automatic.", NullName = "<Auto>", ShortName = "iter, MaxIterations")]
             [TGUI(Label = "Max number of iterations", SuggestedSweeps = "<Auto>,10,20,100")]
             [TlcModule.SweepableDiscreteParam("MaxIterations", new object[] { "<Auto>", 10, 20, 100 })]
-            public int? NumberOfIterations;
+            public int? MaximumNumberOfIterations;
 
             /// <summary>
             /// Determines whether to shuffle data for each training iteration.
@@ -236,7 +236,7 @@ internal virtual void Check(IHostEnvironment env)
                 Contracts.AssertValue(env);
                 env.CheckUserArg(L2Regularization == null || L2Regularization >= 0, nameof(L2Regularization), "L2 constant must be non-negative.");
                 env.CheckUserArg(L1Threshold == null || L1Threshold >= 0, nameof(L1Threshold), "L1 threshold must be non-negative.");
-                env.CheckUserArg(NumberOfIterations == null || NumberOfIterations > 0, nameof(NumberOfIterations), "Max number of iterations must be positive.");
+                env.CheckUserArg(MaximumNumberOfIterations == null || MaximumNumberOfIterations > 0, nameof(MaximumNumberOfIterations), "Max number of iterations must be positive.");
                 env.CheckUserArg(ConvergenceTolerance > 0 && ConvergenceTolerance <= 1, nameof(ConvergenceTolerance), "Convergence tolerance must be positive and no larger than 1.");
 
                 if (L2Regularization < L2LowerBound)
@@ -304,7 +304,7 @@ internal SdcaTrainerBase(IHostEnvironment env, TOptions options, SchemaShape.Col
             SdcaTrainerOptions = options;
             SdcaTrainerOptions.L2Regularization = l2Const ?? options.L2Regularization;
             SdcaTrainerOptions.L1Threshold = l1Threshold ?? options.L1Threshold;
-            SdcaTrainerOptions.NumberOfIterations = maxIterations ?? options.NumberOfIterations;
+            SdcaTrainerOptions.MaximumNumberOfIterations = maxIterations ?? options.MaximumNumberOfIterations;
             SdcaTrainerOptions.Check(env);
         }
 
@@ -443,12 +443,12 @@ private protected sealed override TModel TrainCore(IChannel ch, RoleMappedData d
 
             ch.Check(count > 0, "Training set has 0 instances, aborting training.");
             // Tune the default hyperparameters based on dataset size.
-            if (SdcaTrainerOptions.NumberOfIterations == null)
-                SdcaTrainerOptions.NumberOfIterations = TuneDefaultMaxIterations(ch, count, numThreads);
+            if (SdcaTrainerOptions.MaximumNumberOfIterations == null)
+                SdcaTrainerOptions.MaximumNumberOfIterations = TuneDefaultMaxIterations(ch, count, numThreads);
 
-            Contracts.Assert(SdcaTrainerOptions.NumberOfIterations.HasValue);
+            Contracts.Assert(SdcaTrainerOptions.MaximumNumberOfIterations.HasValue);
             if (SdcaTrainerOptions.L2Regularization == null)
-                SdcaTrainerOptions.L2Regularization = TuneDefaultL2(ch, SdcaTrainerOptions.NumberOfIterations.Value, count, numThreads);
+                SdcaTrainerOptions.L2Regularization = TuneDefaultL2(ch, SdcaTrainerOptions.MaximumNumberOfIterations.Value, count, numThreads);
 
             Contracts.Assert(SdcaTrainerOptions.L2Regularization.HasValue);
             if (SdcaTrainerOptions.L1Threshold == null)
@@ -548,8 +548,8 @@ private protected sealed override TModel TrainCore(IChannel ch, RoleMappedData d
             ch.AssertValue(metricNames);
             ch.AssertValue(metrics);
             ch.Assert(metricNames.Length == metrics.Length);
-            ch.Assert(SdcaTrainerOptions.NumberOfIterations.HasValue);
-            var maxIterations = SdcaTrainerOptions.NumberOfIterations.Value;
+            ch.Assert(SdcaTrainerOptions.MaximumNumberOfIterations.HasValue);
+            var maxIterations = SdcaTrainerOptions.MaximumNumberOfIterations.Value;
 
             var rands = new Random[maxIterations];
             for (int i = 0; i < maxIterations; i++)

src/Microsoft.ML.StandardLearners/StandardLearnersCatalog.cs

@@ -133,7 +133,7 @@ public static SgdNonCalibratedBinaryTrainer StochasticGradientDescentNonCalibrat
         /// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
         /// <param name="l2Regularization">The L2 <a href='tmpurl_regularization'>regularization</a> hyperparameter.</param>
         /// <param name="l1Threshold">The L1 <a href='tmpurl_regularization'>regularization</a> hyperparameter. Higher values will tend to lead to more sparse model.</param>
-        /// <param name="numberOfIterations">The maximum number of passes to perform over the data.</param>
+        /// <param name="maximumNumberOfIterations">The maximum number of passes to perform over the data.</param>
         /// <param name="loss">The custom <a href="tmpurl_loss">loss</a>, if unspecified will be <see cref="SquaredLoss"/>.</param>
         /// <example>
         /// <format type="text/markdown">
@@ -148,11 +148,11 @@ public static SdcaRegressionTrainer StochasticDualCoordinateAscent(this Regressi
             ISupportSdcaRegressionLoss loss = null,
             float? l2Regularization = null,
             float? l1Threshold = null,
-            int? numberOfIterations = null)
+            int? maximumNumberOfIterations = null)
         {
             Contracts.CheckValue(catalog, nameof(catalog));
             var env = CatalogUtils.GetEnvironment(catalog);
-            return new SdcaRegressionTrainer(env, labelColumnName, featureColumnName, exampleWeightColumnName, loss, l2Regularization, l1Threshold, numberOfIterations);
+            return new SdcaRegressionTrainer(env, labelColumnName, featureColumnName, exampleWeightColumnName, loss, l2Regularization, l1Threshold, maximumNumberOfIterations);
         }
 
         /// <summary>
@@ -185,7 +185,7 @@ public static SdcaRegressionTrainer StochasticDualCoordinateAscent(this Regressi
         /// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
         /// <param name="l2Regularization">The L2 <a href='tmpurl_regularization'>regularization</a> hyperparameter.</param>
         /// <param name="l1Threshold">The L1 <a href='tmpurl_regularization'>regularization</a> hyperparameter. Higher values will tend to lead to more sparse model.</param>
-        /// <param name="numberOfIterations">The maximum number of passes to perform over the data.</param>
+        /// <param name="maximumNumberOfIterations">The maximum number of passes to perform over the data.</param>
         /// <example>
         /// <format type="text/markdown">
         /// <![CDATA[
@@ -199,11 +199,11 @@ public static SdcaBinaryTrainer StochasticDualCoordinateAscent(
                 string exampleWeightColumnName = null,
                 float? l2Regularization = null,
                 float? l1Threshold = null,
-                int? numberOfIterations = null)
+                int? maximumNumberOfIterations = null)
         {
             Contracts.CheckValue(catalog, nameof(catalog));
             var env = CatalogUtils.GetEnvironment(catalog);
-            return new SdcaBinaryTrainer(env, labelColumnName, featureColumnName, exampleWeightColumnName, l2Regularization, l1Threshold, numberOfIterations);
+            return new SdcaBinaryTrainer(env, labelColumnName, featureColumnName, exampleWeightColumnName, l2Regularization, l1Threshold, maximumNumberOfIterations);
         }
 
         /// <summary>
@@ -238,7 +238,7 @@ public static SdcaBinaryTrainer StochasticDualCoordinateAscent(
         /// <param name="loss">The custom <a href="tmpurl_loss">loss</a>. Defaults to <see cref="LogLoss"/> if not specified.</param>
         /// <param name="l2Regularization">The L2 <a href='tmpurl_regularization'>regularization</a> hyperparameter.</param>
         /// <param name="l1Threshold">The L1 <a href='tmpurl_regularization'>regularization</a> hyperparameter. Higher values will tend to lead to more sparse model.</param>
-        /// <param name="numberOfIterations">The maximum number of passes to perform over the data.</param>
+        /// <param name="maximumNumberOfIterations">The maximum number of passes to perform over the data.</param>
         /// <example>
         /// <format type="text/markdown">
         /// <![CDATA[
@@ -253,11 +253,11 @@ public static SdcaNonCalibratedBinaryTrainer StochasticDualCoordinateAscentNonCa
                 ISupportSdcaClassificationLoss loss = null,
                 float? l2Regularization = null,
                 float? l1Threshold = null,
-                int? numberOfIterations = null)
+                int? maximumNumberOfIterations = null)
         {
             Contracts.CheckValue(catalog, nameof(catalog));
             var env = CatalogUtils.GetEnvironment(catalog);
-            return new SdcaNonCalibratedBinaryTrainer(env, labelColumnName, featureColumnName, exampleWeightColumnName, loss, l2Regularization, l1Threshold, numberOfIterations);
+            return new SdcaNonCalibratedBinaryTrainer(env, labelColumnName, featureColumnName, exampleWeightColumnName, loss, l2Regularization, l1Threshold, maximumNumberOfIterations);
         }
 
         /// <summary>
@@ -286,7 +286,7 @@ public static SdcaNonCalibratedBinaryTrainer StochasticDualCoordinateAscentNonCa
         /// <param name="loss">The custom <a href="tmpurl_loss">loss</a>. Defaults to <see cref="LogLoss"/> if not specified.</param>
         /// <param name="l2Regularization">The L2 <a href='tmpurl_regularization'>regularization</a> hyperparameter.</param>
         /// <param name="l1Threshold">The L1 <a href='tmpurl_regularization'>regularization</a> hyperparameter. Higher values will tend to lead to more sparse model.</param>
-        /// <param name="numberOfIterations">The maximum number of passes to perform over the data.</param>
+        /// <param name="maximumNumberOfIterations">The maximum number of passes to perform over the data.</param>
         /// <example>
         /// <format type="text/markdown">
         /// <![CDATA[
@@ -300,11 +300,11 @@ public static SdcaMultiClassTrainer StochasticDualCoordinateAscent(this Multicla
                     ISupportSdcaClassificationLoss loss = null,
                     float? l2Regularization = null,
                     float? l1Threshold = null,
-                    int? numberOfIterations = null)
+                    int? maximumNumberOfIterations = null)
         {
             Contracts.CheckValue(catalog, nameof(catalog));
             var env = CatalogUtils.GetEnvironment(catalog);
-            return new SdcaMultiClassTrainer(env, labelColumnName, featureColumnName, exampleWeightColumnName, loss, l2Regularization, l1Threshold, numberOfIterations);
+            return new SdcaMultiClassTrainer(env, labelColumnName, featureColumnName, exampleWeightColumnName, loss, l2Regularization, l1Threshold, maximumNumberOfIterations);
         }
 
         /// <summary>

test/BaselineOutput/Common/EntryPoints/core_manifest.json

@@ -11019,7 +11019,7 @@
           "Default": 1E-07
         },
         {
-          "Name": "NumberOfIterations",
+          "Name": "MaximumNumberOfIterations",
           "Type": "Int",
           "Desc": "Maximum number of iterations.",
           "Aliases": [
@@ -15221,7 +15221,7 @@
           }
         },
         {
-          "Name": "NumberOfIterations",
+          "Name": "MaximumNumberOfIterations",
           "Type": "Int",
           "Desc": "Maximum number of iterations; set to 1 to simulate online learning. Defaults to automatic.",
           "Aliases": [
@@ -15494,7 +15494,7 @@
           }
         },
         {
-          "Name": "NumberOfIterations",
+          "Name": "MaximumNumberOfIterations",
           "Type": "Int",
           "Desc": "Maximum number of iterations; set to 1 to simulate online learning. Defaults to automatic.",
           "Aliases": [
@@ -15767,7 +15767,7 @@
           }
         },
         {
-          "Name": "NumberOfIterations",
+          "Name": "MaximumNumberOfIterations",
           "Type": "Int",
           "Desc": "Maximum number of iterations; set to 1 to simulate online learning. Defaults to automatic.",
           "Aliases": [