Editing Tutorial (section)

===Functions===
Python functions are incredibly useful because you can compartmentalize repeated uses of commonly used '''Flow''' s, and then use them in multiple SConstructs.  For the best use of Python functions you should use the following conventions:
*always use keyword=value arguments to help document your code, 
*list file names for input and output first, then other arguments, 
*use default values for all arguments, even if they are None, 
*use the locals() dictionary to get the values of the arguments, 
*always perform an action inside the function (i.e. create a Flow, Plot or Result), 
*do not return anything from the function, 
*and always accept **kwargs as the last argument to allow for dictionary substitution. 
Here's an example of a well-defined function to create a Ricker wavelet with a peak frequency specified by the user:
<syntaxhighlight lang="python">
def ricker(out='wave',freq=20.0,kt=100,nt=1001,dt=0.01,ot=0.0,**kwargs):
    Flow(out,None,
    	 '''
	 spike n1=%(nt)d o1=%(ot)f d1=%(d1)f 
         nsp=1 mag=1.0 k1=%(kt)d l1=%(kt)d | 
	 ricker1 frequency=%(freq)f 
	 ''' % locals())
</syntaxhighlight>
Notice that we use the python function '''locals()'''  for string substitution.  This function returns a dictionary that contains only the names and values of the named arguments for the function.  
To call this function, you can use it as a normal Python function.  Since there are default arguments, not all arguments need to be passed as long as you are OK with the default value.  
<syntaxhighlight lang="python">
ricker('wave',freq=30,kt=50)
</syntaxhighlight>
If you are using a dictionary that has all of your variables in it, then you can call the function using explicit parameter fetching:
<syntaxhighlight lang="python">
ricker('wave',parameters['freq'],parameters['kt'],...)
</syntaxhighlight>
where you have to explicitly grab certain variables from the parameter dictionary.  Conversely, you can use automatic parameter fetching: 
<syntaxhighlight lang="python">
ricker('wave',**parameters)
</syntaxhighlight>
which will look for all the named arguments to the ricker function in the parameter dictionary, and send their values to the function.  When there are many parameters, and you have already set them in the dictionary, then automatic parameter fetching is the best way to go.