Document how to save programmatic TORAX simulation outputs to disk.

docs/output.rst

@@ -3,10 +3,20 @@
 Simulation output structure
 ###########################
 
-TORAX file output is written to a ``state_history.nc`` netCDF file. If running
-with the ``run_simulation_main.py`` or ``run_torax`` script, the ``output_dir``
-is set via flag ``--output_dir``, with default
-``/tmp/torax_results_<YYYYMMDD_HHMMSS>/``.
+TORAX file output can be written to a NetCDF file. If running with the
+``run_simulation_main.py`` or ``run_torax`` CLI script, output is saved to
+``state_history_<timestamp>.nc`` in the directory set via the ``--output_dir``
+flag (defaulting to ``/tmp/torax_results/``).
+
+When running TORAX programmatically via ``torax.run_simulation()``, outputs
+are returned directly in memory as an ``xarray.DataTree`` rather than written to
+disk automatically. To save them to disk at a specific path, use the
+``to_netcdf()`` method:
+
+.. code-block:: python
+
+  data_tree.to_netcdf('path/to/my_output/state_history.nc')
+
 
 We currently support the below output structure for Torax V1.
 

docs/running_programmatically.rst

@@ -34,8 +34,24 @@ We can then run the simulation:
   # Example below shows how to access the fusion gain at time=2 seconds.
   Q_fusion_t2 = data_tree.scalars.Q_fusion.sel(time=2, method='nearest')
 
+Saving simulation output to disk
+################################
+
+When running TORAX programmatically with ``torax.run_simulation``, simulation
+outputs are returned in memory as an ``xarray.DataTree`` and are not
+automatically written to disk.
+
+To save the simulation output to a NetCDF file (e.g., ``state_history.nc``) at
+any desired location, use the ``to_netcdf()`` method on the returned
+``data_tree``:
+
+.. code-block:: python
+
+  # Save the simulation output to a specific location.
+  data_tree.to_netcdf('path/to/output_directory/state_history.nc')
+
 Plotting from an in-memory simulation
-######################################
+#####################################
 
 If you have already run a simulation and have a ``data_tree`` in memory, you can
 plot it directly without saving to a file first using