Revised: 2004-01-04

Intent+: The purpose of this tutorial is to study the control system
         of an antenna utilizing the Adams Insight ASCII conduit
         and Adams Controls.

         Demonstrate the integration of Adams Insight and
         Adams Controls / Matlab. 
         (See tutorial Learning Adams Controls with MATLAB) 
   
         Investigate how the antenna controls systems parameters
         affect the maximum computed torque.

     Prerequisites
          Basic working knowledge of MATLAB
          Basic working knowledge of Adams Insight
          Basic working knowledge of Adams View and Adams Solver
          Basic working knowledge of how to negotiate a file structure.

          This tutorial assumes that the following components 
          are installed on the machine:
            - Adams View 2005.0 or higher.
            - Adams Insight 2005.0 or higher.
            - MATLAB  
          It is assumed that MATLAB is invoked via the command 
          'matlab' from the DOS or UNIX shell.
Intent-:

Caveats+: Many 
  - Change to DOE screening or Variation - Monte Carlo
    instead of sweep to identify what is significant
Caveats-:


1) Getting the Tutorial Files
 
  - Create a working directory 'asc_ctr' where the exercise will reside. 
    Put the following files in the 'asc_ctr' working directory.  The files
    can be found under the <installation_dir>/ainsight/examples  directory.
   
      ain_tut_102_asc.cmd     (ADAMS model of antenna)
      ain_tut_102_asc.mdl     (MATLAB controls system model)
      ain_tut_102_asc.m       (MATLAB file to define the simulation)
      ain_tut_102_asc.py      (PYTHON script to run simulation) 


    Tip: To determine where the MSC.ADAMS installation resides, type the
    following command in the command prompt window: 
      `adams -top`      Windows
      `mdi -top`        UNIX

  - Copy the following files to new names:
      Windows
        copy ain_tut_102_asc_aco.mdl   plt_mdl.mdl
        copy ain_tut_102_asc_aco.m     plt_run.m
        copy ain_tut_102_asc_aco.py    plt_run.py

      UNIX:
        cp   ain_tut_102_asc_aco.mdl   plt_mdl.mdl
        cp   ain_tut_102_asc_aco.m     plt_run.m
        cp   ain_tut_102_asc_aco.py    plt_run.py


2) Export the Plant Model from Adams View

  - Start Adams View
     `adams aview ru-stan i `     Windows
     `mdi -c aview ru-stan i`     UNIX

  - When the 'How would you like to proceed' panel is raised
    select the 'Import a file' radio button. Then select the 'Ok' button.
    In the 'File to read' field, select the Adams View command file
    ain_tut_102_asc_aco.cmd.

  - From the "Getting Started Using Adams Controls" update the model
    by deactivating the MOTION
     Edit Deactivate  - main_olt  select azimuth_motion_csd

  - Export the plant model to MATLAB:

    Load the controls plugin
      Tools->Plugin Manager ...
       check the "Yes" box in the "controls" row, "Load" column


    From the newly displayed Controls menu, select 
      Controls->Plant Export.

    In the 'Adams Controls Plant Export' window set the fields as follows:

      File Prefix     plt
      Plant Input     tmp_MDI_PINPUT
      Plant Output    tmp_MDI_POUTPUT
      Control Package MATLAB

    Click OK. 

    In the current directory the following files have just been created.
       plt.adm 
       plt.cmd 
       plt.m 

    Exit Adams View  File->Exit


3) Parameterize the Nominal System

  In this section the nominal system defined by the files plt.adm, 
  plt.m, plt_mdl.mdl, plt_run.m and plt_run.py will be parameterized.
   
  Five files represent the nominal system. However, since in this example 
  only the control system parameters need to be parameterized, there is 
  no need to build variants of plt.adm, plt.m and plt_mdl.mdl. Thus, 
  plt_run.m and plt_run.py only need to be parameterized.

  A variant will be built and run in a separate directory, hence one
  needs to make a slight change to plt.m (generated by Adams View) 
  to reference the absolute path of plt.adm.
   
  - Open plt.m in a text editor:
      Edit the file so that ADAMS_prefix references the absolute 
      path of plt.adm:   

      Windows:
        ADAMS_prefix = 'plt' ; -> ADAMS_prefix = strcat(pwd, '\plt') ; 
      UNIX:
        ADAMS_prefix = 'plt' ; -> ADAMS_prefix = strcat(pwd, '/plt') ;

  - Start the ASC Editor from the command prompt from the working 
    directory (asc_ctr) with either of the following command:

      `adams ainsight -ascg`           Windows
      `mdi -c ainsight -ascg exit`     UNIX

  - Import the ASCII files plt_run.m and plt_run.py:
      Select the menu items File->Import and select the file
         plt_run.m  select Ok
      Repeat the operation for plt_run.py

      One will now notice that there are entries in the 
      Templates menu pull down.  The menu also indicates 
      the current active ASC Template
       
  - Annotate the ASCII templates:
      Make the 'plt_run.m' the active ASC Template.

      Highlight the numeric value of Kp.
        Right click and select Create. The 'Create Variable' dialog
        box will be displayed.  Alter the 'Name:' field from the default
        name to 'kp'.  Leave the 'Format:' and 'Value:' fields with their 
        respective default values. Optionally one can key in a description.
      Select OK when done.

      Perform the same procedure as above with the numeric value of Kv. 

  - Edit the plt_run.m file as follows:

    Change the line
    From: 
        run('<working_directory>/plt.m'),
    to:
        run('../plt.m'),

    From:
        run('<working_directory>/plt_mdl.mdl')
    to:
        run('../plt_mdl')


    From:
      fid=fopen('plt_run.dat', 'w')
    to:
      fid=fopen('{{ascTrialName}}__plt_run.dat', 'w').

    Tip: Insert ___ in front of 'plt_run'. Select the first '_'. 
    Right click and select Replace. Select ascTrialName. 
    (This will create a unique variant name for the written results file)

    Note: Make certain there are two underscores

  - Make the 'plt_run.py' the active ASC Template.
    Edit the line:

      From:
        fileName = 'plt_run.m' 
      To:
        fileName = '{{ascTrialName}}__plt_run.m'

    Note: Make certain there are two underscores


    Specify the Execution method for this template by selecting the menu items 
      Edit->Template Properties.

    In the field "Execution Prefix" type the following string:

      'adams python'          Windows
      'mdi -c python'         UNIX

    Note: For Unix add the following to the "Execution Postfix"
      ' Exit '                UNIX

    In the Post Operations (Dict) text box, enter
        {'max_torque':'dat:absmax:1'} 

    Note: An ASC System consists of one or more ASC Templates.  Each 
          ASC Template has its own set or properties. 
          In the tutorial, make certain to edit the template properties 
          of the plt_run.py template and not that of the plt_run.m file.  
 
  - Specify the name of the ASC System by selecting File->ASC Properties... 
    In the ASC System Properties dialog box, fill in the 
    'Name:' field with 'ctr.'

  - Save the ASC system by selecting File->Save As 'ctr'

  - Export an Adams Insight experiment file 
     File->Export Experiment
       

    Note: Two files are created in the current directory: 
          An ASC System file ctr.xml 
          A default Adams Insight experiment file  ctr_exp.xml


4) Design the experiment:

  - Start Adams Insight by hitting the Display Adams Insight tool bar button.
    (The newly exported ctr_exp.xml is automatically loaded)

  - The Factors and Responses have automatically been generated are
    in the Inclusions lists 


  - Select the desired Investigation Strategy:
    Under Design Specification select Study - Sweep for the 
    Investigation Strategy. Set Number of Runs to 8. 
    Next create the Work Space. One should now  
    have a Work Space with 8 trials.

5. Write Multi Event Regulator (MER) File

   - Hit the calculator button. 
   - Click Yes on the question if you want to process the ASC system 
     file 'ctr.xml'.
   - Click OK.  

   Note: The result of this operation is that a newly created *_mer.py 
   file has been generated in the current directory. This file can be 
   utilized to build, run and post-process the ASC system(s) defined 
   in the *_mer.py file.

   Adams Insight will shut down and you will be back in Adams Insight ASC

6. Run the Multi Event Regulator (MER) File

   - To determine whether a variant is truely different then
     the nominal hit the ASC MER - diff button on the toolbar 
     This will display each asc template nominal and the first variant.


   - To test the configuration and run only the first trial, 
     Hit the ASC MER - Run one trial toolbar button
     Note:
       Monitor the originating command promt window
       for the progress of the matlab operations 

   - Investigate the newly created files in the newly generated
     subdirectory 'tst_dir'

     Open a command prompt window and move to the 'asc_ctr' 
     working directory.  Change directory down to tst_dir


   - Now run all the trials by hitting the ASC MER - Run all Trials button

   Note: All of the ASC MER toolbar button operations are available 
         from the command line. 

    For Example
     - For help on using the *_mer.py file, type:
       `adams python ctr_exp_mer.py -h`            Windows
       `mdi -c  python ctr_exp_mer.py -h exit`     UNIX
 
     - To test the configuration and run only the first trial, 
       issue the following command:

        `adams   python ctr_exp_mer.py`            Windows
        `mdi -c  python ctr_exp_mer.py exit`       UNIX

     - Now run all the trials
       `adams   python ctr_exp_mer.py -t`          Windows
       `mdi -c  python ctr_exp_mer.py -t exit`     UNIX


7) Import the results into Adams Insight

  - Return to Adams Insight by selecting the Adams Insight tool bar
    button.  Once in Adams Insight read the results in.
      File->Import->Results

  - Select the directory below the current directory 'tst_dir' and
    the .csv file  'tst_pos.csv.'

  - Review the Work Space matrix by clicking on the workspace leaf 
    in the Adams Insight tree under the Design leaf


End: