class_docstr: This class exists so that we can easily read a configuration file with the `allennlp train`
  command.  The basic logic is that we call `train_loop =
  TrainModel.from_params(params_from_config_file)`, then `train_loop.run()`.  This class performs
  very little logic, pushing most of it to the `Trainer` that has a `train()` method.  The
  point here is to construct all of the dependencies for the `Trainer` in a way that we can do
  it using `from_params()`, while having all of those dependencies transparently documented and
  not hidden in calls to `params.pop()`.  If you are writing your own training loop, you almost
  certainly should not use this class, but you might look at the code for this class to see what
  we do, to make writing your training loop easier.
  
  In particular, if you are tempted to call the `__init__` method of this class, you are probably
  doing something unnecessary.  Literally all we do after `__init__` is call `trainer.train()`.  You
  can do that yourself, if you've constructed a `Trainer` already.  What this class gives you is a
  way to construct the `Trainer` by means of a config file.  The actual constructor that we use
  with `from_params` in this class is `from_partial_objects`.  See that method for a description
  of all of the allowed top-level keys in a configuration file used with `allennlp train`.
class_docstr_tok: ["This","class","exists","so","that","we","can","easily","read","a","configuration","file","with","the","`","allennlp","train","`","command",".","The","basic","logic","is","that","we","call","`","train_loop","=","TrainModel.from_params","(","params_from_config_file",")","`",",","then","`","train_loop.run","(",")","`",".","This","class","performs","very","little","logic",",","pushing","most","of","it","to","the","`","Trainer","`","that","has","a","`","train","(",")","`","method",".","The","point","here","is","to","construct","all","of","the","dependencies","for","the","`","Trainer","`","in","a","way","that","we","can","do","it","using","`","from_params","(",")","`",",","while","having","all","of","those","dependencies","transparently","documented","and","not","hidden","in","calls","to","`","params.pop","(",")","`",".","If","you","are","writing","your","own","training","loop",",","you","almost","certainly","should","not","use","this","class",",","but","you","might","look","at","the","code","for","this","class","to","see","what","we","do",",","to","make","writing","your","training","loop","easier",".","In","particular",",","if","you","are","tempted","to","call","the","`","__init__","`","method","of","this","class",",","you","are","probably","doing","something","unnecessary",".","Literally","all","we","do","after","`","__init__","`","is","call","`","trainer.train","(",")","`",".","You","can","do","that","yourself",",","if","you","'ve","constructed","a","`","Trainer","`","already",".","What","this","class","gives","you","is","a","way","to","construct","the","`","Trainer","`","by","means","of","a","config","file",".","The","actual","constructor","that","we","use","with","`","from_params","`","in","this","class","is","`","from_partial_objects","`",".","See","that","method","for","a","description","of","all","of","the","allowed","top-level","keys","in","a","configuration","file","used","with","`","allennlp","train","`","."]
docstr: This method is intended for use with our `FromParams` logic, to construct a `TrainModel`
  object from a config file passed to the `allennlp train` command.  The arguments to this
  method are the allowed top-level keys in a configuration file (except for the first three,
  which are obtained separately).
  
  You *could* use this outside of our `FromParams` logic if you really want to, but there
  might be easier ways to accomplish your goal than instantiating `Lazy` objects.  If you are
  writing your own training loop, we recommend that you look at the implementation of this
  method for inspiration and possibly some utility functions you can call, but you very likely
  should not use this method directly.
  
  The `Lazy` type annotations here are a mechanism for building dependencies to an object
  sequentially - the `TrainModel` object needs data, a model, and a trainer, but the model
  needs to see the data before it's constructed (to create a vocabulary) and the trainer needs
  the data and the model before it's constructed.  Objects that have sequential dependencies
  like this are labeled as `Lazy` in their type annotations, and we pass the missing
  dependencies when we call their `construct()` method, which you can see in the code below.
  
  # Parameters
  
  serialization_dir: `str`
      The directory where logs and model archives will be saved.
  
      In a typical AllenNLP configuration file, this parameter does not get an entry as a
      top-level key, it gets passed in separately.
  
  local_rank: `int`
      The process index that is initialized using the GPU device id.
  
      In a typical AllenNLP configuration file, this parameter does not get an entry as a
      top-level key, it gets passed in separately.
  
  dataset_reader: `DatasetReader`
      The `DatasetReader` that will be used for training and (by default) for validation.
  
  train_data_path: `str`
      The file (or directory) that will be passed to `dataset_reader.read()` to construct the
      training data.
  
  model: `Lazy[Model]`
      The model that we will train.  This is lazy because it depends on the `Vocabulary`;
      after constructing the vocabulary we call `model.construct(vocab=vocabulary)`.
  
  data_loader: `Lazy[DataLoader]`
      The data_loader we use to batch instances from the dataset reader at training and (by
      default) validation time. This is lazy because it takes a dataset in it's constructor.
  
  trainer: `Lazy[Trainer]`
      The `Trainer` that actually implements the training loop.  This is a lazy object because
      it depends on the model that's going to be trained.
  
  vocabulary: `Lazy[Vocabulary]`, optional (default=`Lazy(Vocabulary)`)
      The `Vocabulary` that we will use to convert strings in the data to integer ids (and
      possibly set sizes of embedding matrices in the `Model`).  By default we construct the
      vocabulary from the instances that we read.
  
  datasets_for_vocab_creation: `List[str]`, optional (default=`None`)
      If you pass in more than one dataset but don't want to use all of them to construct a
      vocabulary, you can pass in this key to limit it.  Valid entries in the list are
      "train", "validation" and "test".
  
  validation_dataset_reader: `DatasetReader`, optional (default=`None`)
      If given, we will use this dataset reader for the validation data instead of
      `dataset_reader`.
  
  validation_data_path: `str`, optional (default=`None`)
      If given, we will use this data for computing validation metrics and early stopping.
  
  validation_data_loader: `Lazy[DataLoader]`, optional (default=`None`)
      If given, the data_loader we use to batch instances from the dataset reader at
      validation and test time. This is lazy because it takes a dataset in it's constructor.
  
  test_data_path: `str`, optional (default=`None`)
      If given, we will use this as test data.  This makes it available for vocab creation by
      default, but nothing else.
  
  evaluate_on_test: `bool`, optional (default=`False`)
      If given, we will evaluate the final model on this data at the end of training.  Note
      that we do not recommend using this for actual test data in every-day experimentation;
      you should only very rarely evaluate your model on actual test data.
  
  batch_weight_key: `str`, optional (default=`""`)
      The name of metric used to weight the loss on a per-batch basis.  This is only used
      during evaluation on final test data, if you've specified `evaluate_on_test=True`.
  
  ddp_accelerator : `Optional[DdpAccelerator]`, optional (default = `None`)
      A `DdpAccelerator` to use in distributed trainer. Passed to the model and the trainer.
docstr_tok: ["This","method","is","intended","for","use","with","our","`","FromParams","`","logic",",","to","construct","a","`","TrainModel","`","object","from","a","config","file","passed","to","the","`","allennlp","train","`","command",".","The","arguments","to","this","method","are","the","allowed","top-level","keys","in","a","configuration","file","(","except","for","the","first","three",",","which","are","obtained","separately",")",".","You","*","could","*","use","this","outside","of","our","`","FromParams","`","logic","if","you","really","want","to",",","but","there","might","be","easier","ways","to","accomplish","your","goal","than","instantiating","`","Lazy","`","objects",".","If","you","are","writing","your","own","training","loop",",","we","recommend","that","you","look","at","the","implementation","of","this","method","for","inspiration","and","possibly","some","utility","functions","you","can","call",",","but","you","very","likely","should","not","use","this","method","directly",".","The","`","Lazy","`","type","annotations","here","are","a","mechanism","for","building","dependencies","to","an","object","sequentially","-","the","`","TrainModel","`","object","needs","data",",","a","model",",","and","a","trainer",",","but","the","model","needs","to","see","the","data","before","it","'s","constructed","(","to","create","a","vocabulary",")","and","the","trainer","needs","the","data","and","the","model","before","it","'s","constructed",".","Objects","that","have","sequential","dependencies","like","this","are","labeled","as","`","Lazy","`","in","their","type","annotations",",","and","we","pass","the","missing","dependencies","when","we","call","their","`","construct","(",")","`","method",",","which","you","can","see","in","the","code","below",".","#","Parameters","serialization_dir",":","`","str","`","The","directory","where","logs","and","model","archives","will","be","saved",".","In","a","typical","AllenNLP","configuration","file",",","this","parameter","does","not","get","an","entry","as","a","top-level","key",",","it","gets","passed","in","separately",".","local_rank",":","`","int","`","The","process","index","that","is","initialized","using","the","GPU","device","id",".","In","a","typical","AllenNLP","configuration","file",",","this","parameter","does","not","get","an","entry","as","a","top-level","key",",","it","gets","passed","in","separately",".","dataset_reader",":","`","DatasetReader","`","The","`","DatasetReader","`","that","will","be","used","for","training","and","(","by","default",")","for","validation",".","train_data_path",":","`","str","`","The","file","(","or","directory",")","that","will","be","passed","to","`","dataset_reader.read","(",")","`","to","construct","the","training","data",".","model",":","`","Lazy","[","Model","]","`","The","model","that","we","will","train",".","This","is","lazy","because","it","depends","on","the","`","Vocabulary","`",";","after","constructing","the","vocabulary","we","call","`","model.construct","(","vocab=vocabulary",")","`",".","data_loader",":","`","Lazy","[","DataLoader","]","`","The","data_loader","we","use","to","batch","instances","from","the","dataset","reader","at","training","and","(","by","default",")","validation","time",".","This","is","lazy","because","it","takes","a","dataset","in","it","'s","constructor",".","trainer",":","`","Lazy","[","Trainer","]","`","The","`","Trainer","`","that","actually","implements","the","training","loop",".","This","is","a","lazy","object","because","it","depends","on","the","model","that","'s","going","to","be","trained",".","vocabulary",":","`","Lazy","[","Vocabulary","]","`",",","optional","(","default=","`","Lazy","(","Vocabulary",")","`",")","The","`","Vocabulary","`","that","we","will","use","to","convert","strings","in","the","data","to","integer","ids","(","and","possibly","set","sizes","of","embedding","matrices","in","the","`","Model","`",")",".","By","default","we","construct","the","vocabulary","from","the","instances","that","we","read",".","datasets_for_vocab_creation",":","`","List","[","str","]","`",",","optional","(","default=","`","None","`",")","If","you","pass","in","more","than","one","dataset","but","do","n't","want","to","use","all","of","them","to","construct","a","vocabulary",",","you","can","pass","in","this","key","to","limit","it",".","Valid","entries","in","the","list","are","``","train","''",",","``","validation","''","and","``","test","''",".","validation_dataset_reader",":","`","DatasetReader","`",",","optional","(","default=","`","None","`",")","If","given",",","we","will","use","this","dataset","reader","for","the","validation","data","instead","of","`","dataset_reader","`",".","validation_data_path",":","`","str","`",",","optional","(","default=","`","None","`",")","If","given",",","we","will","use","this","data","for","computing","validation","metrics","and","early","stopping",".","validation_data_loader",":","`","Lazy","[","DataLoader","]","`",",","optional","(","default=","`","None","`",")","If","given",",","the","data_loader","we","use","to","batch","instances","from","the","dataset","reader","at","validation","and","test","time",".","This","is","lazy","because","it","takes","a","dataset","in","it","'s","constructor",".","test_data_path",":","`","str","`",",","optional","(","default=","`","None","`",")","If","given",",","we","will","use","this","as","test","data",".","This","makes","it","available","for","vocab","creation","by","default",",","but","nothing","else",".","evaluate_on_test",":","`","bool","`",",","optional","(","default=","`","False","`",")","If","given",",","we","will","evaluate","the","final","model","on","this","data","at","the","end","of","training",".","Note","that","we","do","not","recommend","using","this","for","actual","test","data","in","every-day","experimentation",";","you","should","only","very","rarely","evaluate","your","model","on","actual","test","data",".","batch_weight_key",":","`","str","`",",","optional","(","default=","`","``","''","`",")","The","name","of","metric","used","to","weight","the","loss","on","a","per-batch","basis",".","This","is","only","used","during","evaluation","on","final","test","data",",","if","you","'ve","specified","`","evaluate_on_test=True","`",".","ddp_accelerator",":","`","Optional","[","DdpAccelerator","]","`",",","optional","(","default","=","`","None","`",")","A","`","DdpAccelerator","`","to","use","in","distributed","trainer",".","Passed","to","the","model","and","the","trainer","."]
code: def from_partial_objects(
      cls,
      serialization_dir: str,
      local_rank: int,
      dataset_reader: DatasetReader,
      train_data_path: Any,
      model: Lazy[Model],
      data_loader: Lazy[DataLoader],
      trainer: Lazy[Trainer],
      vocabulary: Lazy[Vocabulary] = Lazy(Vocabulary),
      datasets_for_vocab_creation: List[str] = None,
      validation_dataset_reader: DatasetReader = None,
      validation_data_path: Any = None,
      validation_data_loader: Lazy[DataLoader] = None,
      test_data_path: Any = None,
      evaluate_on_test: bool = False,
      batch_weight_key: str = "",
      ddp_accelerator: Optional[DdpAccelerator] = None,
  ) -> "TrainModel":
      """
      This method is intended for use with our `FromParams` logic, to construct a `TrainModel`
      object from a config file passed to the `allennlp train` command.  The arguments to this
      method are the allowed top-level keys in a configuration file (except for the first three,
      which are obtained separately).
  
      You *could* use this outside of our `FromParams` logic if you really want to, but there
      might be easier ways to accomplish your goal than instantiating `Lazy` objects.  If you are
      writing your own training loop, we recommend that you look at the implementation of this
      method for inspiration and possibly some utility functions you can call, but you very likely
      should not use this method directly.
  
      The `Lazy` type annotations here are a mechanism for building dependencies to an object
      sequentially - the `TrainModel` object needs data, a model, and a trainer, but the model
      needs to see the data before it's constructed (to create a vocabulary) and the trainer needs
      the data and the model before it's constructed.  Objects that have sequential dependencies
      like this are labeled as `Lazy` in their type annotations, and we pass the missing
      dependencies when we call their `construct()` method, which you can see in the code below.
  
      # Parameters
  
      serialization_dir: `str`
          The directory where logs and model archives will be saved.
  
          In a typical AllenNLP configuration file, this parameter does not get an entry as a
          top-level key, it gets passed in separately.
  
      local_rank: `int`
          The process index that is initialized using the GPU device id.
  
          In a typical AllenNLP configuration file, this parameter does not get an entry as a
          top-level key, it gets passed in separately.
  
      dataset_reader: `DatasetReader`
          The `DatasetReader` that will be used for training and (by default) for validation.
  
      train_data_path: `str`
          The file (or directory) that will be passed to `dataset_reader.read()` to construct the
          training data.
  
      model: `Lazy[Model]`
          The model that we will train.  This is lazy because it depends on the `Vocabulary`;
          after constructing the vocabulary we call `model.construct(vocab=vocabulary)`.
  
      data_loader: `Lazy[DataLoader]`
          The data_loader we use to batch instances from the dataset reader at training and (by
          default) validation time. This is lazy because it takes a dataset in it's constructor.
  
      trainer: `Lazy[Trainer]`
          The `Trainer` that actually implements the training loop.  This is a lazy object because
          it depends on the model that's going to be trained.
  
      vocabulary: `Lazy[Vocabulary]`, optional (default=`Lazy(Vocabulary)`)
          The `Vocabulary` that we will use to convert strings in the data to integer ids (and
          possibly set sizes of embedding matrices in the `Model`).  By default we construct the
          vocabulary from the instances that we read.
  
      datasets_for_vocab_creation: `List[str]`, optional (default=`None`)
          If you pass in more than one dataset but don't want to use all of them to construct a
          vocabulary, you can pass in this key to limit it.  Valid entries in the list are
          "train", "validation" and "test".
  
      validation_dataset_reader: `DatasetReader`, optional (default=`None`)
          If given, we will use this dataset reader for the validation data instead of
          `dataset_reader`.
  
      validation_data_path: `str`, optional (default=`None`)
          If given, we will use this data for computing validation metrics and early stopping.
  
      validation_data_loader: `Lazy[DataLoader]`, optional (default=`None`)
          If given, the data_loader we use to batch instances from the dataset reader at
          validation and test time. This is lazy because it takes a dataset in it's constructor.
  
      test_data_path: `str`, optional (default=`None`)
          If given, we will use this as test data.  This makes it available for vocab creation by
          default, but nothing else.
  
      evaluate_on_test: `bool`, optional (default=`False`)
          If given, we will evaluate the final model on this data at the end of training.  Note
          that we do not recommend using this for actual test data in every-day experimentation;
          you should only very rarely evaluate your model on actual test data.
  
      batch_weight_key: `str`, optional (default=`""`)
          The name of metric used to weight the loss on a per-batch basis.  This is only used
          during evaluation on final test data, if you've specified `evaluate_on_test=True`.
  
      ddp_accelerator : `Optional[DdpAccelerator]`, optional (default = `None`)
          A `DdpAccelerator` to use in distributed trainer. Passed to the model and the trainer.
  
      """
      # Train data loader.
      data_loaders: Dict[str, DataLoader] = {
          "train": data_loader.construct(
              reader=dataset_reader, data_path=train_data_path
          )
      }
  
      # Validation data loader.
      if validation_data_path is not None:
          validation_dataset_reader = (
              validation_dataset_reader or dataset_reader
          )
          if validation_data_loader is not None:
              data_loaders[
                  "validation"
              ] = validation_data_loader.construct(
                  reader=validation_dataset_reader,
                  data_path=validation_data_path,
              )
          else:
              data_loaders["validation"] = data_loader.construct(
                  reader=validation_dataset_reader,
                  data_path=validation_data_path,
              )
              if (
                  getattr(
                      data_loaders["validation"],
                      "batches_per_epoch",
                      None,
                  )
                  is not None
              ):
                  warnings.warn(
                      "Using 'data_loader' params to construct validation data loader since "
                      "'validation_data_loader' params not specified, but you have "
                      "'data_loader.batches_per_epoch' set which may result in different "
                      "validation datasets for each epoch.",
                      UserWarning,
                  )
  
      # Test data loader.
      if test_data_path is not None:
          test_dataset_reader = (
              validation_dataset_reader or dataset_reader
          )
          if validation_data_loader is not None:
              data_loaders["test"] = validation_data_loader.construct(
                  reader=test_dataset_reader, data_path=test_data_path
              )
          else:
              data_loaders["test"] = data_loader.construct(
                  reader=test_dataset_reader, data_path=test_data_path
              )
  
      if datasets_for_vocab_creation:
          for key in datasets_for_vocab_creation:
              if key not in data_loaders:
                  raise ConfigurationError(
                      f"invalid 'dataset_for_vocab_creation' {key}"
                  )
  
          logger.info(
              "From dataset instances, %s will be considered for vocabulary creation.",
              ", ".join(datasets_for_vocab_creation),
          )
  
      instance_generator = (
          instance
          for key, data_loader in data_loaders.items()
          if datasets_for_vocab_creation is None
          or key in datasets_for_vocab_creation
          for instance in data_loader.iter_instances()
      )
  
      vocabulary_ = vocabulary.construct(instances=instance_generator)
  
      model_ = model.construct(
          vocab=vocabulary_,
          serialization_dir=serialization_dir,
          ddp_accelerator=ddp_accelerator,
      )
  
      # Initializing the model can have side effect of expanding the vocabulary.
      # Save the vocab only in the primary. In the degenerate non-distributed
      # case, we're trivially the primary. In the distributed case this is safe
      # to do without worrying about race conditions since saving and loading
      # the vocab involves acquiring a file lock.
      if local_rank == 0:
          vocabulary_path = os.path.join(
              serialization_dir, "vocabulary"
          )
          vocabulary_.save_to_files(vocabulary_path)
  
      for data_loader_ in data_loaders.values():
          data_loader_.index_with(model_.vocab)
  
      trainer_ = trainer.construct(
          serialization_dir=serialization_dir,
          model=model_,
          data_loader=data_loaders["train"],
          validation_data_loader=data_loaders.get("validation"),
          local_rank=local_rank,
          ddp_accelerator=ddp_accelerator,
      )
      assert trainer_ is not None
  
      return cls(
          serialization_dir=serialization_dir,
          model=model_,
          trainer=trainer_,
          evaluation_data_loader=data_loaders.get("test"),
          evaluate_on_test=evaluate_on_test,
          batch_weight_key=batch_weight_key,
      )
  
imports: import argparse
  import logging
  import os
  from os import PathLike
  from typing import Any, Dict, List, Optional, Union
  import warnings
  import torch
  import torch.distributed
  import torch.multiprocessing
  from allennlp.commands.subcommand import Subcommand
  from allennlp.common import Params, Registrable, Lazy
  from allennlp.common.checks import check_for_gpu, ConfigurationError
  from allennlp.common.meta import Meta, META_NAME
  from allennlp.common import logging
  from allennlp.common import util
  from allennlp.common.plugins import import_plugins
  from allennlp.data import DatasetReader, Vocabulary
  from allennlp.data import DataLoader
  from allennlp.models.archival import archive_model, CONFIG_NAME, verify_include_in_archive
  from allennlp.models.model import Model
  from allennlp.nn.parallel import DdpAccelerator
  from allennlp.training.trainer import Trainer
  from allennlp.training import util
label_desc: Use image node_id 4 for calling the TrainModel obj's underlying member method code with example usage: obj.from_partial_objects(cls, serialization_dir, local_rank, dataset_reader, train_data_path, model, data_loader, trainer, vocabulary, datasets_for_vocab_creation, validation_dataset_reader, validation_data_path, validation_data_loader, test_data_path, evaluate_on_test, batch_weight_key, ddp_accelerator) and returns: cls