<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE html
  SYSTEM "about:legacy-compat">
<html xmlns:mml = "http://www.w3.org/1998/Math/MathML" lang = "en"><head><meta charset = "UTF-8"/><meta name = "copyright" content = "(C) Copyright 2020"/><meta name = "DC.rights.owner" content = "(C) Copyright 2020"/><meta name = "DC.type" content = "reference"/><meta name = "abstract" content = "This section shows how to configure the execution of custom modules at certain points of the Python Driver workflow."/><meta name = "description" content = "This section shows how to configure the execution of custom modules at certain points of the Python Driver workflow."/><meta name = "DC.format" content = "HTML5"/><meta name = "DC.identifier" content = "tso-r-cmd-driver-hooks"/><meta name = "DC.language" content = "en"/><link rel = "stylesheet" type = "text/css" href = "../DSDocUI_XML34.css"/><title>User Script Entry Points ("Hooks")</title>
<script type = "text/javascript" src = "../DSDocUI_Highlight34.js">
  	/* */
  	</script></head><body onLoad = "highlightSearchTerms();" id = "tso-r-cmd-driver-hooks">
<a name = "hj-top"> </a><table class = "table1" id = "table11"><tr><td><table class = "DocHeader"><tr><td class = "DocHeader1" colspan = "2"><h1>User Script Entry Points ("Hooks")</h1></td></tr><tr><td class = "DocHeader4" colspan = "2"/></tr><tr><td class = "DocHeader3" colspan = "2"><table class = "DocThemeIntro" id = "table12"><tr><td class = "Intro1Only"><p class = "header"><p class = "abstract">
<span class = "shortdesc">This section shows how to configure the execution of custom modules at certain points of the Python Driver workflow.</span>

</p>
<p>This page discusses: </p><ul><li><a href = "#tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-general-info" id = "toc_rg" title = "">Definitions and Overview</a></li><li><a href = "#tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-setup-module" id = "toc_rg" title = "">Setting-up Module Hooks</a></li><li><a href = "#tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-setup-check-point" id = "toc_rg" title = "">Setting-up Check-Point Hooks</a></li><li><a href = "#tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-cmd-line" id = "toc_rg" title = "">Command Line for the Hook-Modules</a></li></ul>
</p></td></tr></table></td></tr></table>




<div class = "body refbody">


<div class = "section" id = "tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-general-info"><h2 class = "title sectiontitle">Definitions and Overview</h2>
  
  <p>User Script Entry Points, called "hooks," are optional steps in the <a class = "xref" href = "../TsoUserMap/tso-m-usr-control-general-test-sb.htm#tso-m-usr-control-general-test-sb" title = "SIMULIA Tosca Structure consists of many individual software modules that load the FE input and result data or modify the input files when required. The complete optimization process is controlled from one principal module named SIMULIA Tosca Structure Control. It controls the calling sequence of the individual software modules and the relevant solver."><span class = "ph">Tosca Structure</span> Control</a> workflow where a user-defined call to an
        external module can be established. The terms "hooks" and "User Script Entry Points" are
        used interchangeably in this guide.</p>
  <p>There are two types of hooks supported by the Python Driver:
  <ol class = "ol">
    <li class = "li">Module hooks—executed before/after a specific <span class = "ph">Tosca</span> Module. For a list of the <span class = "ph">Tosca</span> Modules,
            refer to <a class = "xref" href = "tso-r-cmd-driver-modRedef.htm#tso-r-cmd-driver-modRedef" title = "This section shows how the default executable modules can be redefined and overridden with user-provided modules.">Redefinition of the Tosca
              Modules</a>.</li>
    <li class = "li">Check point hooks—executed before/after save rules at a given "check point" of the optimization process; for example, at the beginning and/or end of a design cycle, at the  beginning/end of the entire optimization, etc.</li>
  </ol></p>
  <p>In general, both types execute the user script the same way. The only differences are the hook
        setup and the state of the optimization process. Hooks can be accumulated; that is, multiple
        user scripts can be attached to the same module/check point, and they will be executed in
        the order in which they were registered.</p>
  <p>The Python Driver will spawn a new process for each individual hook, and it will be executed
        synchronously. Optionally, the driver can pass the current design cycle and the perturbation
        number as command line arguments to the process. This feature is ON by default. For all
        post-processing modules (report, smooth, onf2sim), as well as for all preprocessing modules
        (step2lc, fem_include, fem2onf, fem_modif, and tosca_prep), the current design cycle and
        perturbation number are always 0. The user can provide additional command-line arguments to
        be passed to the hook-modules executed. These additional arguments to the hook are evaluated
        once by the Python Driver before the start of the optimization and remain constant
        throughout the run. For a detailed description of the possibilities to customize any
        command-line arguments to the hook-calls, refer to the <a class = "xref" href = "tso-r-cmd-driver-hooks.htm#tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-cmd-line">section on command-line options below</a>. </p>
  <p>All hook start files (user scripts or executables), if not specified by the full path, are expected to be located in the directory of the job input-files.
  The files themselves are not moved, no matter how they are specified, but the working directory for the hook-modules is always the <span class = "ph">Tosca</span> working directory.
  </p>
</div>



<div class = "section" id = "tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-setup-module"><p><map name = "FPMap1"><area href = "#hj-top" title = "Back to Top" shape = "rect" coords = "416, 0, 435, 10"/></map><span class = "itemsprite"/></p><h2 class = "title sectiontitle">Setting-up Module Hooks</h2>
  <p> A module hook can be attached to any module that the driver executes. If the specific module
        is not called during the optimization process, any attached hooks are not called.
        Optionally, the Python Driver can pass the command line of the module the hook is attached
        to. This feature is OFF by default. </p>

  <p>Registering a module hook can be done in two ways:</p>
  <dl class = "dl">
   <dt class = "dt dlterm">General Hook Registration</dt>
   <dd class = "dd">
   <p>The most generic way to attach a hook is by using the method <code class = "ph codeph">registerModuleHook()</code>.</p>
  <p> In the following example, a script is executed before the call to the <span class = "ph">Tosca</span> module tosca_opt.
              <pre class = "codeblock">
    <code class = "ph codeph">DRIVER</code>
    <code class = "ph codeph">  driver.registerModuleHook( ToscaModules.TOSCA_OPT, HookTypes.PRE, EventTimes.EVER, 'script.bat --arg1 a1' )</code>
    <code class = "ph codeph">END_</code>
  </pre> After evaluation of the hook-definition by the Python Driver, the
              following actual call to the user script will be performed, <pre class = "codeblock">
    <code class = "ph codeph">script.bat --arg1 a1 --cycle &lt;i&gt; --perturbation &lt;p&gt;</code>
  </pre> where <code class = "ph codeph">&lt;i&gt;</code> and <code class = "ph codeph">&lt;p&gt;</code> are the
              current design cycle and perturbation, respectively. </p>
  <p>
    The arguments of a call to <code class = "ph codeph">registerModuleHook()</code> are as follows:
  <pre class = "codeblock">
    <code class = "ph codeph">driver.registerModuleHook( module, type, time, command, addIterPert = True, addArgs = False )</code>
  </pre>
  </p>
  <p>
  <ul class = "ul">
    <li class = "li"><p>The argument <code class = "ph codeph">module</code> specifies to which <span class = "ph">Tosca</span> module the hook should be attached. Specify one of the following:
    <ul class = "ul">
      <li class = "li"><code class = "ph codeph">ToscaModules.ABQ_LC_STEP</code></li>
      <li class = "li"><code class = "ph codeph">ToscaModules.FEM_INCLUDE</code></li>
      <li class = "li"><code class = "ph codeph">ToscaModules.FEM_2_ONF</code></li>
      <li class = "li"><code class = "ph codeph">ToscaModules.FEM_MODIF</code></li>
      <li class = "li"><code class = "ph codeph">ToscaModules.TOSCA_PREP</code></li>
      <li class = "li"><code class = "ph codeph">ToscaModules.TOSCA_OPT</code></li>
      <li class = "li"><code class = "ph codeph">ToscaModules.RES_2_VTM</code> (non-<span class = "ph">Abaqus</span>)</li>
      <li class = "li"><code class = "ph codeph">ToscaModules.ODB_2_VTM</code> (<span class = "ph">Abaqus</span>)</li>
      <li class = "li"><code class = "ph codeph">ToscaModules.LIFE_2_VTM</code></li>
      <li class = "li"><code class = "ph codeph">PostTypes.REPORT</code></li>
      <li class = "li"><code class = "ph codeph">PostTypes.SMOOTH</code></li>
      <li class = "li"><code class = "ph codeph">PostTypes.ONF_2_SIM</code></li>
      <li class = "li"><code class = "ph codeph">FeSolvers.ABAQUS</code></li>
      <li class = "li"><code class = "ph codeph">FeSolvers.MSCNASTRAN</code></li>
      <li class = "li"><code class = "ph codeph">LifeSolvers.ONF</code></li>
      <li class = "li"><code class = "ph codeph">LifeSolvers.FESAFE</code></li>
      <li class = "li"><code class = "ph codeph">LifeSolvers.FEMFAT</code></li>
    </ul></p>
        
    </li>
    <li class = "li"><p>Argument <code class = "ph codeph">type</code> specifies when the user script should be executed. The possible values are:<ul class = "ul"><li class = "li"><code class = "ph codeph">HookTypes.PRE</code>: before the <span class = "ph">Tosca</span> module execution</li>
	<li class = "li"><code class = "ph codeph">HookTypes.POST</code>: after the Tosca module execution</li><li class = "li"><code class = "ph codeph">HookTypes.PRE_POST</code>: both before and after the <span class = "ph">Tosca</span> module execution</li></ul></p>
        
    </li>
    <li class = "li"><p>The argument <code class = "ph codeph">time</code> defines how often the hook-script should be executed. It can be one of the following:
    <ul class = "ul">
      <li class = "li"><code class = "ph codeph">EventTimes.EVER</code>: every time</li>
      <li class = "li"><code class = "ph codeph">EventTimes.NEVER</code>: never</li>
      <li class = "li"><code class = "ph codeph">EventTimes.FIRST</code>: only the first time</li>
      <li class = "li"><code class = "ph codeph">EventTimes.LAST</code>: only the last time (Only selectable for <code class = "ph codeph">PostTypes</code>)</li>
      <li class = "li"><code class = "ph codeph">EventTimes.FIRST_LAST</code>: only the first and the last time (Only selectable for <code class = "ph codeph">PostTypes</code>)</li>
      <li class = "li"><code class = "ph codeph">EventTimes.NTH</code>: only once, the N<sup class = "ph sup">th</sup>-time</li>
      <li class = "li"><code class = "ph codeph">EventTimes.FREQ</code>: every N<sup class = "ph sup">th</sup>-time</li></ul></p>
    </li>
    <li class = "li"><p>The argument <code class = "ph codeph">command</code> is a string-value Python expression that should be used to evaluate a system call to be executed for the hook.
           Typically this is a string that can contain format-specifiers plus variables/expressions to fill these format-specifiers with values.
           For examples and further details, refer to the <a class = "xref" href = "tso-r-cmd-driver-hooks.htm#tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-cmd-line">section on command-line options below</a>.
        </p></li>
    <li class = "li"><p><code class = "ph codeph">addIterPert</code> is an optional flag-argument (default value: True) that triggers the addition of design cycle and perturbation to the hook-script command line.
           The user script would get the following arguments added to its command line: <code class = "ph codeph">--cycle &lt;i&gt; --perturbation &lt;p&gt;</code>, where <code class = "ph codeph">&lt;i&gt;</code> and <code class = "ph codeph">&lt;p&gt;</code> are the current design cycle and perturbation, respectively.
        </p>
    </li>
    <li class = "li"><p>The optional argument <code class = "ph codeph">addArgs</code> (default value: False) instructs the Python Driver whether to add the command line arguments of the <span class = "ph">Tosca</span> module to the command line of the user-script.
        </p>
    </li>
  </ul>
  </p>
  </dd>
  
  
    <dt class = "dt dlterm">Hook Registration through the <code class = "ph codeph">Pre</code>/<code class = "ph codeph">Post</code> Shortcuts</dt>
    <dd class = "dd">
    <p>A simpler syntax is provided to register hooks using the <code class = "ph codeph">Pre</code> and <code class = "ph codeph">Post</code> properties of the existing modules as shortcuts:<pre class = "codeblock">
    <code class = "ph codeph">&lt;module&gt;.Pre = &lt;command&gt;</code>
  </pre>
    or<pre class = "codeblock">
    <code class = "ph codeph">&lt;module&gt;.Post = &lt;command&gt;</code>
  </pre>
  Behind the scenes the general method <code class = "ph codeph">registerModuleHook()</code> is used,
  whereas the default values are used except for the command line and the module name.</p>

<p>Example—assigning a hook to be executed after the solver is finished:</p>

  <pre class = "codeblock">
    <code class = "ph codeph">DRIVER</code>
    <code class = "ph codeph">  driver.Solver.Post = 'post_solver.py --arg1 a1 --arg2 a2'</code>
    <code class = "ph codeph">END_</code>
  </pre>

This assignment is equivalent to the following call, assuming the current solver is <span class = "ph">Abaqus</span>:

  <pre class = "codeblock">
    <code class = "ph codeph">DRIVER</code>
    <code class = "ph codeph">  driver.registerModuleHook( FeSolvers.ABAQUS, HookTypes.POST, EventTimes.EVER, 'post_solver.py --arg1 a1 --arg2 a2', addIterPert = True, addArgs = False )</code>
    <code class = "ph codeph">END_</code>
  </pre>
  </dd>
  
  </dl>

</div>



<div class = "section" id = "tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-setup-check-point"><p><map name = "FPMap1"><area href = "#hj-top" title = "Back to Top" shape = "rect" coords = "416, 0, 435, 10"/></map><span class = "itemsprite"/></p><h2 class = "title sectiontitle">Setting-up Check-Point Hooks</h2>
  <p>
    A check-point hook can be attached to events in the course of an optimization job; for example, at the beginning and/or end of a design cycle, at the beginning/end of the entire optimization, etc.
  </p>
  <p>
    The arguments of a call to <code class = "ph codeph">registerCheckPointHook()</code> are as follows:
  <pre class = "codeblock">
    <code class = "ph codeph">driver.registerCheckPointHook( checkPoint, type, time, command, addIterPert = True )</code>
  </pre>
  </p>
  <p>
  <ul class = "ul">
    <li class = "li"><p>The argument <code class = "ph codeph">checkPoint</code> specifies the event to which the hook should be attached. Provide one of the following:<ul class = "ul"><li class = "li"><code class = "ph codeph">CheckPoints.CYCLE_COMPLETE</code>: after a design cycle is completed</li><li class = "li"><code class = "ph codeph">CheckPoints.OPT_COMPLETE</code>: after the whole optimization is completed</li><li class = "li"><code class = "ph codeph">CheckPoints.MX_COMPLETE</code>: after a matrix cycle is completed</li><li class = "li"><code class = "ph codeph">CheckPoints.OPT_BEGIN</code>: the optimization is about to begin</li></ul></p>
        
    </li>
    <li class = "li"><p>Argument <code class = "ph codeph">type</code> specifies when the user script should be executed. The possible values are:<ul class = "ul"><li class = "li"><code class = "ph codeph">HookTypes.PRE</code>: before the execution of the <a class = "xref" href = "tso-r-cmd-driver-cfgDriverProp.htm#tso-r-cmd-driver-cfgDriverProp__tso-r-cmd-driver-cfgDriverProp-driver-regSaveRule">save-rules</a> for this check-point</li><li class = "li"><code class = "ph codeph">HookTypes.POST</code>: after the execution of the <a class = "xref" href = "tso-r-cmd-driver-cfgDriverProp.htm#tso-r-cmd-driver-cfgDriverProp__tso-r-cmd-driver-cfgDriverProp-driver-regSaveRule">save-rules</a> for this check-point</li><li class = "li"><code class = "ph codeph">HookTypes.PRE_POST</code>: both before and after the execution of the <a class = "xref" href = "tso-r-cmd-driver-cfgDriverProp.htm#tso-r-cmd-driver-cfgDriverProp__tso-r-cmd-driver-cfgDriverProp-driver-regSaveRule">save-rules</a> for this check-point</li></ul></p>
        
        
    </li>
    <li class = "li"><p>The argument <code class = "ph codeph">time</code> defines how often the hook-script should be executed. It can be one of the following:<ul class = "ul"><li class = "li"><code class = "ph codeph">EventTimes.EVER</code>: every time</li><li class = "li"><code class = "ph codeph">EventTimes.NEVER</code>: never</li><li class = "li"><code class = "ph codeph">EventTimes.FIRST</code>: only the first time</li><li class = "li"><code class = "ph codeph">EventTimes.LAST</code>: only the last time</li><li class = "li"><code class = "ph codeph">EventTimes.FIRST_LAST</code>: only the first and the last time</li><li class = "li"><code class = "ph codeph">EventTimes.NTH</code>: only once, the N<sup class = "ph sup">th</sup>-time</li><li class = "li"><code class = "ph codeph">EventTimes.FREQ</code>: every N<sup class = "ph sup">th</sup>-time</li></ul></p>
        
    </li>
    <li class = "li"><p>The argument <code class = "ph codeph">command</code> is a string-value Python expression that should be used to evaluate  a system call to be executed for the hook.
           Typically this is a string that can contain format-specifiers plus variables/expressions to fill these format-specifiers with values.
           For examples and further details, refer to the <a class = "xref" href = "tso-r-cmd-driver-hooks.htm#tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-cmd-line">section on command-line options below</a>.
        </p></li>
    <li class = "li"><p><code class = "ph codeph">addIterPert</code> is an optional flag-argument (default value: True) that triggers the addition of design cycle and perturbation to the hook-script command line.
           The user script would get the following arguments added to its command line: <code class = "ph codeph">--cycle &lt;i&gt; --perturbation &lt;p&gt;</code>, where <code class = "ph codeph">&lt;i&gt;</code> and <code class = "ph codeph">&lt;p&gt;</code> are the current design cycle and perturbation, respectively.
        </p>
    </li>
  </ul>
  </p>
</div>



<div class = "section" id = "tso-r-cmd-driver-hooks__tso-r-cmd-driver-hooks-cmd-line"><p><map name = "FPMap1"><area href = "#hj-top" title = "Back to Top" shape = "rect" coords = "416, 0, 435, 10"/></map><span class = "itemsprite"/></p><h2 class = "title sectiontitle">Command Line for the Hook-Modules</h2>
  <p>The command line of the hook-module can be given as a string or as a list of strings. The
        Python Driver can natively execute python files (.py), as well as shell scripts for the
        corresponding platform: .bat, .cmd, .sh, etc. For example, passing the type of the
        optimization: <pre class = "codeblock">
    <code class = "ph codeph">'script.bat --optype "%s"' % str( driver.OptimizationType )</code>
  </pre> evaluates to<pre class = "codeblock">
    <code class = "ph codeph">script.bat --optype "Topo Sensitivity"</code>
  </pre> Example—passing the title of the results file: <pre class = "codeblock">
    <code class = "ph codeph">'script.bat --resfile %s' % OptimizationTypes.toOnf( driver.OptimizationType )</code>
  </pre> evaluates to<pre class = "codeblock">
    <code class = "ph codeph">script.bat --resfile TP</code>
  </pre>
      </p>
</div>


</div>

</td></tr></table><script type = "text/javascript" src = "../DSDocUI_Bottom34.js">/* */</script></body>
</html>
