Creates a virtual project, or a real project.
  Modifies existing projects.
  
 
 
 
  INPUT:
 
         project name:
 
                     1) A string to name a new project to be created.
 
                     2) a virtual project already in the Matlab workspace.
 
                     3) a directory name that designates a real project already in disk.
                        Dynamo will find the file that contains the project
                        design and bring it into the workspace.
 
 
   PARAMETER/VALUE
 
   Passing project parameters:
 
      - when the 'project' argument is a new argument to be created
        (parameters). In this case, parameters not passed explicitely
        are filled with default values, unless you explicite that you
        want to import them from another project (with flag 'seedsfrom')
        or that you request a suggestion for a reasonable guess (with
        flag "hint")
 
      - when the 'project' argument is an existing project to be modified.
 
   1- Dynamo project parameters
 
      'Parameter_name', Parameter_value
      This defines which parameters of the old project will
      get a new value assigned directly from the input instead of a default value.
      For parameters that are defined on different rounds,
      the user can also pass Parameter_value as a cellarray {} or an array []
      in order to set all parameters of all rounds at once.
 
      A list of all parameters can be viewed with dynamo_vpr_help
 
 
   2- Additional parameters (shorthand)
 
      You can use the shorthands:
      'table','data','template','mask','cmask'and 'fmask'
      (or even their own shornames 't','d','template','m','cm','fm')
      to pass these parameters instead of the standard (and rather cumbersome)
      names of these parameters ('file_table_initial' and so on).
 
      With the shorthand notation you can also pass numeric values instead
      of just names of folders or files.
 
 
   3- Alternatives
 
      Database notation is usually clearer for command line interactive
      sessions when just short modifications in an existing project are
      intended. For instance:
 
      dv my_project -ite_r1 8
 
      is equivalent to:
 
      ddb my_project:ite_r1 put 8
 
      or just
    
      dvput my_project ite_r1 8
      which write in disk the porject with the new parameter.
 
 
      SEE ALSO
      dvput, dynamo_db.
 
    4- Multireference projects
    --------------------------
    
    If the project under creation is supposed to be multireference, just
    pass the number of references as the flag 'nref'.
    By default, this way of initializing a project as multireference will
    switch on the "particle swapping" between multireference channels.
    This means that the multireference project will classify and align
    simultanteousy 
    Note that if you use this option you do not need to use the plugin
    system to indicate dynamo that you want to use the multirefrence
    plugin. 
 
    EXAMPLE
    dv myproject -d data -t folderWithseeds -nref 4
 
    For advanced users:
    This explicite "nref" initialization amounts to state that the project will
    initialize by itself with the right values for the parameters 
    'nref','mra','plugin_post' and 'plugin_post_order'.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
   More accepted input parameters:
 
  -------------------------------------------------------------------------
 
   Project actions:
   ---------------
 
     'new'             :   logical, 0/1
                           An option to "protect" projects already existing
                           in the disk from accidental modification.
                           If the flag is switched on, it forces dynamo_vpr
                           to abort if the project being managed is already
                           in the disk.
                           - default: false
 
     'copyof'          :  - string (name of a Dynamo project)
                           - vpr structure (virtual Dynamo project)
                           Passing this parameter indicates that 'project'
                           (the first argument) will be created by copying
                           all the linked contents (seeds as table,
                           template, etc, and numerical settings)
                           of the project indicated by 'seedsfrom'.
                           Results will not be copied!
                           - default: [] (the new project is filled with
                                          default values)
 
     'roundsfrom'      :   like 'copyof' but importing only the
                           parameters that determine the alignment rounds
                           (angular scans, multigrid parameters, CC settings...)
 
 
     'links2dbd'       :   logical, 0/1
                           "seed" files are normally "linked" into a project:
                           i.e., the project includes some project
                           parameteters, for instance
                           "file_template_initial", which are pointing to
                           some file. Let's say as example, some file
                           called 'template.em'.
                           If you use this option, this file will be copied
                           into the database of the project, so that you
                           have a secured copy of 'template.em' inside the
                           project, and also know that this file was
                           intended to be used as template in the project.
 
                           - default: false / empty (do nothing)
 
 
     'dbd2seeds'       :   logical, 0/1.
                            This flag is not exactly the "inverse" action
                            of link2dbd.
                            When switched on, Dynamo checks the "seed" files
                            (mask, tempplate, etc) physically present
                            in the database of the project.
                            If they exist and are coherent, dynamo_vpr will
                            then let the corresponding "project parameters"
                            (i.e.: 'file_mask','file_template_initial') to
                            point to these files that are ensured to reside
                            in the disk.
                            Following the example initiated in the previos
                            flag, this option would prevent your project
                            from pointing to a file that might have been
                            removed (or even worse, edited) since the
                            moment that the project was created.
 
                           - default: false / empty (do nothing)
 
  -------------------------------------------------------------------------
 
   Preparing execution
   -------------------
 
   Note that the default behavior of 'dynamo_vpr' is saving the virtual
   project in the disk.
 
 
     'check'           :   logical, 0/1 char(on/off)
                           checks the viability of the project.
                           - default: false
 
     'unfold'          :   logical, 0/1, char(on/off)
                           unfolds the project if checking is correct.
                           - default: false
 
     'unfold_force'    :   logical, 0/1
                           tryes to unfold the project even it checking
                           is not correct.
                           - default: false
 
     Recommended method: the flag "save"
 
     'save','s'        :   string with different combinations of actions
                           'd'  saves in disk the created or modified project
                                without performing any check.
                           'c'  checks the project.
                           'cd' checks and saves in disk only if check is
                                correct;
                           'u'  unfolds the project if checks correctly.
                                Note that "unfolding" includes saving the
                                modifications into disk and checking.
                           'uf' force-unfold the project, even without
                                checking.
                           'no' do not save, do not check
                           'n'  respects other user input flags ('unfold' and 'check');
                            - default: 'd': saves the modifications in disk.
 
    SEE ALSO
        dynamo_vpr_check, dynamo_vpr_run, dynamo_vpr_unfold,
        dynamo_vpr_rewind
 
  -------------------------------------------------------------------------
 
   "Hints":
   -------
 
    Generation of reasonable suggestion for project parameters.
 
   * Suggestions for required project files ("seeds") and project numerical
     settings can be automatically generated with these flags.
 
   * By defaults all the flags in this section are inactive: you need to
     invoke them explicitely (possibly assigning some of the values
     explained below).
 
   * Note, however that these suggestions will not overwrite the project
     parameters that you pass explicitely from the command line.
 
 
 
     'hint_files'       :    A flag that can be used to command Dynamo to
                             directly create the "project files" needed
                             to start a project.
                             As input, you can pass any combination of the
                             strings:
                            'table' 'template' 'mask 'cmask' 'fmask'
                            - as cell array: {'table','cmask'}
                            - as comma separated string: 'table,mask'
                            - as '|' separaterd string:  'table|mask'
                            - the code '*' or 'all' to indicate that all
                              the parameters need to be computed.
                            - the code 'volumes' for the combination: 
                                         template|mask|cmask|fmask
                            - the code 'masks' for the combination: 
                                         mask|cmask|fmask   
 
     'hint_settings'    :   To generate suggestions for the numerical
                            parameters of the project:
                            angular samplings, iteration number, etc...
                            string with possible values:
                            - 'refine' : a suggestion for numeric parameters
                                         intended for refining an existing
                                         table is generated and passed.
                            - 'search' : numeric parameters for searching
                                         the initial orientations are
                                         generated.
                            - 'none'   : skip suggestion of numeric
                                         parameters
 
                            default: 'none'
 
 
     'hint'             :  shorthand for the two previous flags. The user
                           passes a string with values:
 
                           - 'all'       : to generate all files (and no
                                           numerical settings)
 
                           - 'all,refine': to generate all files (and also
                                           numerical settings for refinement)
 
                           - 'all,search': to generate all files (and also
                                           numerical settings for search)
 
                           - a list {} of file items that can include the codes
                            'refine' or 'search' to indicate  which kind of
                             hints for numerical settings are required.
                             (absence of such codes skips generation of
                              suggestions for numerical settings).
                           - This list can also be passed as a comma
                             separated string.
 
 
     EXAMPLE ("hints")
 
     To create a full project ab initio using only the data as input.
 
     % In Matlab
     dynamo_vpr('my_name','data','my_data','hint','all','save','d');
     % or
     dv my_name -data my_data -hint all -save d;
 
     % in the Dynamo console
     Dynamo >> vpr my_name -data my_data -hint all unfold on;
 
     The previous will NOT create numerical iteration parameters.
     You can use instead:
     dv my_name data my_data hint all|refine save d;
 
     SEE ALSO
         dynamo_vpr_hint_files, dynamo_vpr_hint_settings
 
 
  -------------------------------------------------------------------------
 
  Show project elements
  ---------------------
 
    This is a legacy functionality: current versions of Dynamo have a
    better coverage of these issues throught database queries (ddb).
    View the help of dynamo_db for more information.
 
 
   'show'               :  string.
                           lists file names of results or seeds inside a
                           project.
                           Valid choices:
                           - 'seeds','results','cc'
                           - 'template','data','mask','cmask','fmask'...
                           - 'info'     : summary information on the
                                          project.
                           - 'infotable': information on the initial table
 
                         : database location (string)
                           This flag can be used to quickly retrieve elements
                           of the database of the project.
                           The notation for this use is:
                           database_item:locator1=value1:locator2=value2
                           without spaces in between.
                           For instance:
                           dynamo_vpr my_project show average:ite=*:ref=1
                           dynamo_vpr my_project show table:ite=2:ref=3
                           etc...
                           The locator values are parsed and passed to
                           dynamo_database_locate, so that all the syntax
                           allowed in that function ('last','end','*') can
                           also be used here.
 
 
  SEE ALSO
      dynamo_vpr_files, dynamo_vpr_results, dynamo_vpr_info,
      dynamo_table_info, dynamo_vpr_status, dynamo_database_locate
 
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
   OUTPUT
 
   Besides all the files that might be created upon unfolding of the
   project, the return to the command line is:
 
         new_vpr:        virtual project structure.
                         (Empty object if the dynamo_vpr fails execution)
 
  -------------------------------------------------------------------------
 
 
 
  EXAMPLES
 
  % Creates a blank virtual project with default settings
   vpr = dynamo_vpr('some_name');
   % vpr is now just a matlab variable, it is still not a project in disk!
 
 
  % creates a blank virtual project indicating the initial table and the data
   vpr = dynamo_vpr('some_name','table',my_table,'data',my_data);
 
  % creates a project indicating the data
  %
  dynamo_vpr('some_name','data',my_data,'hint','all');%
 
 
 
  
  Functional and string notation:
 
  %  modifies three parameters in an existing project
  %  then unfolds it
  dynamo_vpr my_project -ite_r1 20 -ite_r1 20 -sym_r2 c1 -unfold 1;
  % note here the string notation, that can be used both in
  % standalone modus and Matlab version.
  % The functional notation equivalent would be:
  dynamo_vpr('my_project','ite_r1',20,'ite_r1',20,'sym_r2','c1','unfold',1);
  % which can be used from Matlab
 
 
 
 
 
 
  SEE ALSO:
  dynamo_project_mamager % main GUI for controlling all the project parameters
  dynamo_vpr_modify      % direct modification of project parameters
  dynamo_vpr_help        % lists syntax of project parameters