Merge pull request #548 from xjjiang/CLI_defaults

Document all CLI defaults

aviary/docs/getting_started/onboarding_level1.ipynb

@@ -119,8 +119,6 @@
     "\n",
     "- `--phase_info`: Path to phase info file. If not provided, it is `default_phase_info/gasp.py` if Mission origin is `2DOF` and `default_phase_info/flops.py` for `simple`.\n",
     "\n",
-    "- `--n2`: Generate an n2 diagram after the analysis. “[N2](https://openmdao.org/newdocs/versions/latest/features/model_visualization/n2_basics/n2_basics.html)” diagram is an OpenMDAO helper to visualize the model (see [details](https://openmdao.org/newdocs/versions/latest/features/model_visualization/n2_details/n2_details.html) too and [tutorial](https://www.youtube.com/watch?v=42VtbX6CX3A)). It is highly recommended that this option is turned on for new users.\n",
-    "\n",
     "- `--max_iter`: Maximum number of iterations. Default is 50.\n",
     "\n",
     "- `shooting`: Use shooting instead of collocation.\n",

aviary/docs/user_guide/aviary_commands.ipynb

@@ -133,6 +133,20 @@
     "!aviary run_mission -h"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`input_deck` is the path to vehicle input deck .csv file.\n",
+    "`-o` or `--outdir` is the directory to write outputs. The default is current directory.\n",
+    "`--optimizer` is the name of the optimizer. The default is `SNOPT`.\n",
+    "`--shooting` indicates that the integration method is shooting method instead of collocation scheme. The default is collocation.\n",
+    "`--phase_info` is the path to phase info file. If it is missing, it depends on the integration method (collocation or shooting) and on the mission method (settings:equations+of_motion with value of `2DOF` or `height_energy`) which is defined in the .csv input file.\n",
+    "`--max_iter` is the maximum number of iterations. The default is 50.\n",
+    "\n",
+    "More detailed discussions can be found in [onboarding_level1](../getting_started/onboarding_level1.ipynb)."
+   ]
+  },
   {
    "attachments": {},
    "cell_type": "markdown",
@@ -143,9 +157,14 @@
     "\n",
     "The `aviary fortran_to_aviary` command will convert a Fortran input deck to an Aviary csv.\n",
     "\n",
-    "The only required input is the filepath to the input deck.\n",
-    "Optionally, a deck of default values can be specified, this is useful if an input deck assumes certain values for any unspecified variables.\n",
+    "The only two required inputs are `-l` (for `--legacy_code` with options `FLOPS` and `GASP`) and the filepath to the input deck. \n",
+    "Optionally, a deck of default values can be specified via the option `-d` (for `--defaults_deck`) and a default deck file, this is useful if an input deck assumes certain values for any unspecified variables.\n",
+    "When this command is run, a brief message is printed. To print more messages, one can set verbosity level higher. For example, `-v 3` will result in debug messages being printed. See [Controlling Display Levels](../developer_guide/coding_standards.ipynb) for more details.\n",
     "If an invalid filepath is given, pre-packaged resources will be checked for input decks with a matching name.\n",
+    "If the output file name is not specified, a detault name is assumed to be the trunk of the input file name with `csv` as file extension. For example, an input file `sample.dat` will result in `sample_converted.csv`.\n",
+    "If the output file exists, the command will not run unless the user specifies `--force` to force the overwritten action.\n",
+    "\n",
+    "Here, pre-packaged resources are absolute path, relative path, and Aviary based path.\n",
     "\n",
     "Notes for input decks:\n",
     "- FLOPS, GASP, or Aviary names can be used for variables (Ex WG or Mission:Design:GROSS_MASS)\n",
@@ -163,6 +182,11 @@
     "aircraft:fuselage:pressure_differential = .5, atm !DELP in GASP, but using atmospheres instead of psi\n",
     "ARNGE(1) = 3600 !target range in nautical miles\n",
     "pyc_phases = taxi, groundroll, rotation, landing\n",
+    "```\n",
+    "\n",
+    "Example usage:\n",
+    "```\n",
+    "`aviary fortran_to_aviary --legacy_code GASP --force GASP_test.dat` Convert the GASP input deck to Aviary (even if an output exists).\n",
     "```\n"
    ]
   },
@@ -201,7 +225,7 @@
     "\n",
     "The only required input is the name of an input deck.\n",
     "This can be specified as the name of the file, the path from [aviary/models](https://github.com/OpenMDAO/Aviary/tree/main/aviary/models), the name of a folder in aviary/models. Multiple files and folders can be copied at once.\n",
-    "Optionally, the output directory can be specified; if it is not, the files will be copied into the current working directory in a folder called aviary_models.\n",
+    "Optionally, the output directory can be specified; if it is not, the files will be copied into the current working directory in a folder called `aviary_models`.\n",
     "If specified, the output directory will be created as needed.\n",
     "\n",
     "Example usage:\n",
@@ -270,9 +294,16 @@
     "\n",
     "The `aviary convert_engine` command will convert a legacy formatted (FLOPS or GASP) engine deck into an Aviary formatted engine deck.\n",
     "\n",
-    "Users must provide the path or name of an input deck, the path to the output file, and the engine format being converted.\n",
+    "Users must provide the path or name of an input deck, and the engine format being converted.\n",
     "If an invalid filepath is given for the input file, pre-packaged resources will be checked for input decks with a matching name.\n",
     "\n",
+    "The path to the output file name is optional. If it is missing, the output file name takes the \n",
+    "trunk of the input file name with `deck` as default file extension. For example, an input file `sample.eng` will result in `sample.deck` unless the user specifies the output file name.\n",
+    "\n",
+    "If the output file exists, it will be overwritten.\n",
+    "\n",
+    "The engine format is specified by `-f` or `--data_format` with one of `FLOPS`, `GASP`, and `GASP_TP` string. If multiple are specified, the last one will be used.\n",
+    "\n",
     "Notes for input decks:\n",
     "- Turbofan decks for both FLOPS and GASP can be converted\n",
     "- Turboshaft decks for GASP can also be converted\n",
@@ -340,7 +371,9 @@
     "The `aviary convert_aero_table` command will convert a legacy formatted (FLOPS or GASP) aero table into an Aviary formatted aero table.\n",
     "\n",
     "Users must provide the path or name of an input deck and the data format being converted.\n",
-    "Optionally, the path to the output file can also be specified, otherwise the default output file will be in the same location and have the same name as input file, but with '_aviary' appended to filename.\n",
+    "Optionally, the path to the output file can also be specified, otherwise the default output file will be in the same location and have the same name as input file, but with '_aviary' appended to the end of filename trunk while the file extension is preserved. For example, an input file `sample.txt` will result in `sample_aviary.txt` unless the user specifies the output file name.\n",
+    "If both `-f` and `--data_format` are specified, the later one is taken.\n",
+    "If an existing file has the same name as output file name, the existing file will be overwritten.\n",
     "If an invalid filepath is given for the input file, pre-packaged resources will be checked for input decks with a matching name.\n",
     "\n",
     "Notes for input decks:\n",
@@ -352,7 +385,13 @@
     "\n",
     "Example usage:\n",
     "```\n",
-    "`aviary convert_aero_table -f GASP subsystems/aerodynamics/gasp_based/data/GASP_aero_free.txt large_single_aisle_1_aero_flaps.txt` Convert a GASP based aero table\n",
+    "`aviary convert_aero_table -f GASP subsystems/aerodynamics/gasp_based/data/GASP_aero_free.txt large_single_aisle_1_aero_flaps.txt` Convert a GASP based aero table\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "`aviary convert_aero_table -f FLOPS utils/test/flops_test_polar.txt aviary_flops_polar.txt` Convert a FLOPS based aero table\n",
     "```\n"
    ]
@@ -406,7 +445,7 @@
     "(aviary-PMC-command)=\n",
     "### aviary convert_prop_table\n",
     "\n",
-    "The `aviary convert_prop_table` command will convert a legacy formatted (GASP) propeller map into an Aviary formatted propeller map.\n",
+    "The `aviary convert_prop_table` command will convert a legacy formatted (GASP) propeller map into an Aviary formatted propeller map. Currently, it is the only format allowed and so it is the default format.\n",
     "\n",
     "Users must provide the path or name of an input deck, the path to the output file, and the engine format being converted.\n",
     "If an invalid filepath is given for the input file, pre-packaged resources will be checked for input decks with a matching name.\n",
@@ -420,10 +459,11 @@
     "```\n",
     "`aviary convert_prop_table -f GASP PropFan.map PropFan.prop` Convert a GASP based propeller map\n",
     "`aviary convert_prop_table -f GASP general_aviation.map general_aviation.prop` Convert a GASP based propeller map\n",
+    "`aviary convert_prop_table general_aviation.map` Convert a GASP based propeller map\n",
     "```\n",
     "\n",
     "The first example uses Mach number and the second example uses helical Mach number. \n",
-    "Note that the output file name can be skipped. Since there is only one input data format is supported at this time, input data format is defaulted to GASP if not provided."
+    "Note that the output file name can be skipped as demonstrated in the third example. Since there is only one input data format that is supported at this time, it defaults to GASP if not provided. This is shown in the third example as well."
    ]
   },
   {
@@ -447,6 +487,72 @@
    "source": [
     "!aviary convert_prop_table -h"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "(aviary-draw-command)=\n",
+    "### aviary draw_mission\n",
+    "\n",
+    "The `aviary draw_mission` command will bring up a new graphical interface for users to create a  mission. This command does not have an input. More details can be found at [Drawing and running simple missions](drawing_and_running_simple_missions.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "(aviary-plot-command)=\n",
+    "### aviary plot_drag_polar\n",
+    "\n",
+    "The `aviary plot_drag_polar` command will bring up a new graphical interface for users to draw drag polar. No options are needed on the command line but a file explorer window will pop-up to allow the user to select a drag polar file (a `.csv` file). It is not working at this time."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!aviary plot_drag_polar -h"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "(aviary-dashboard-command)=\n",
+    "### aviary dashboard\n",
+    "\n",
+    "The `aviary dashboard` command will bring up a dashboard that lets the user easily browse between the reports and files that are generated during an Aviary run."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!aviary dashboard -h"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To use this utility, either a problem has been run or a run script is provided.\n",
+    "\n",
+    "`--problem_recorder` is an input. Default is `problem_history.db`.\n",
+    "`--driver_recorder` is an optional input.\n",
+    "`--port` is the dashboard server port ID. The default is `0` meaning any free port.\n",
+    "`-b` or `--background` indicates to run in background. Default is `False`.\n",
+    "`-d` or `--debug` indicates to show debugging output. Default is `False`.\n",
+    "`--save` is the name of zip file in which dashboard files are saved. If no argument given, use the script name to name the zip file.\n",
+    "`--force` indicates to overwrite the saved zip file. The default is `False`.\n",
+    "`script_name` is the name of aviary script that was run (not including .py), or the csv input filename if the user runs a Level 1 script.\n",
+    "\n",
+    "More discussion on `aviary dashboard` command can be found in [Postprocessing and Visualizing Results from Aviary](postprocessing_and_visualizing_results.ipynb)."
+   ]
   }
  ],
  "metadata": {

aviary/interface/methods_for_level1.py

@@ -111,7 +111,6 @@ def run_level_1(
     outdir='output',
     optimizer='SNOPT',
     phase_info=None,
-    n2=False,
     max_iter=50,
     analysis_scheme=AnalysisScheme.COLLOCATION,
 ):
@@ -141,15 +140,15 @@ def run_level_1(
 
     prob = run_aviary(input_deck, phase_info, **kwargs)
 
-    if n2:
-        outfile = os.path.join(outdir, "n2.html")
-        if outdir != '':
-            os.makedirs(outdir, exist_ok=True)
-        om.n2(
-            prob,
-            outfile=outfile,
-            show_browser=False,
-        )
+    # update n2 diagram after run.
+    outfile = os.path.join(outdir, "n2.html")
+    if outdir != '':
+        os.makedirs(outdir, exist_ok=True)
+    om.n2(
+        prob,
+        outfile=outfile,
+        show_browser=False,
+    )
 
     return prob
 
@@ -175,8 +174,6 @@ def _setup_level1_parser(parser):
         default=None,
         help="Path to phase info file"
     )
-    parser.add_argument("--n2", action="store_true",
-                        help="Generate an n2 diagram after the analysis")
     parser.add_argument(
         "--max_iter",
         type=int,
@@ -212,7 +209,6 @@ def _exec_level1(args, user_args):
         outdir=args.outdir,
         optimizer=args.optimizer,
         phase_info=args.phase_info,
-        n2=args.n2,
         max_iter=args.max_iter,
         analysis_scheme=analysis_scheme,
     )