Profiling and Optimization Guide: Start Here
============================================

This short guide describes a number of practical ways in which you can improve
the performance of your Katana scenes and reduce render time. We also explore a
number of systematic methods by which you can analyse you Katana scene to limit
the time you need to spend optimising your scene.

At times, some of these recommendations may appear contradictory.
This is intentional: scene graphs, their Ops and inputs vary significantly
between projects. What works for one scene may cause a slow down in others.
Profiling and optimisation should be an iterative, results driven process;
with experience, you will develop an intuition as to what works well in
certain situations and for certain scenes.

A general workflow pattern for optimizing Katana scene traversal is as follows,

1. Identify an optimization target e.g. time to first pixel, memory reduction
   in cook() calls.
2. Identify thread unsafe ops and refactor where possible to allow parallel
   evaluation. Measure against (1).
3. Identify the most costly ops in the op tree.
     a. Analyze these ops and where possible optimize the code.
        Measure against (1).
     b. Repeat for as many ops as practicable.
4. Analyze data dependencies in the scene graph to exploit op tree parallelism.
     a. Refactor node graph where appropriate
5. Tune cache settings.

Using scenewalker
-----------------

To streamline this workflow, Katana includes a utility called ``scenewalker``,
found at ``$KATANA_ROOT/bin/scenewalker``. This allows you to traverse the scene
graph without launching Katana, giving a much smaller surface area for profiling
and debugging. ``scenewalker`` is also able to output the same JSON file
generated by a Preview Render with Profiling.

Before using ``scenewalker``, a serialized OpTree must be generated using the
"Save Serialized OpTree to Disk` option in the Debug section of Katana's Render
Menu:

.. image:: SaveSerializedOpTree.png

This will output an ``.optree`` file to Katana's temporary directory, whose full
path is written to the console that launched Katana. Copy this file somewhere
accessible.

To cook the entire scene graph, run ``scenewalker`` as::

    /path/to/scenewalker /path/to/serialized.optree

Alternatively, to only cook a single location, run ``scenewalker`` as::

    /path/to/scenewalker /path/to/serialized.optree --location /location/to/cook

To enable Geolib3-MT Runtime profiling and output a profiling file, run
``scenewalker`` with the command line argument
``--profile /path/to/output.json``. This outputs the same JSON file created by
a Preview Render with Profiling at the given path.