pycall Opcodes
Prev | Orchestra Opcodes and Operators | Next

## pycall Opcodes

pycall — Invoke the specified Python callable at k-time and i-time (i suffix), passing the given arguments. The call is perfomed in the global environment, and the result (the returning value) is copied into the Csound output variables specified.

## Syntax

                                            pycall   "callable", karg1, ...
    kresult                                 pycall1  "callable", karg1, ...
    kresult1, kresult2                      pycall2  "callable", karg1, ...
    kr1, kr2, kr3                           pycall3  "callable", karg1, ...
    kr1, kr2, kr3, kr4                      pycall4  "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5                 pycall5  "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6            pycall6  "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6, kr7       pycall7  "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6, kr7, kr8  pycall8  "callable", karg1, ...

                                            pycallt   ktrigger, "callable", karg1, ...
    kresult                                 pycall1t  ktrigger, "callable", karg1, ...
    kresult1, kresult2                      pycall2t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3                           pycall3t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4                      pycall4t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5                 pycall5t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6            pycall6t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6, kr7       pycall7t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6, kr7, kr8  pycall8t  ktrigger, "callable", karg1, ...

                                            pycalli   "callable", karg1, ...
    iresult                                 pycall1i  "callable", iarg1, ...
    iresult1, iresult2                      pycall2i  "callable", iarg1, ...
    ir1, ir2, ir3                           pycall3i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4                      pycall4i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4, ir5                 pycall5i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4, ir5, ir6            pycall6i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4, ir5, ir6, ir7       pycall7i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4, ir5, ir6, ir7, ir8  pycall8i  "callable", iarg1, ...

    pycalln   "callable", nresults, kresult1, ..., kresultn, karg1, ...
    pycallni  "callable", nresults, iresult1, ..., iresultn, iarg1,  ...

                                            pylcall   "callable", karg1, ...
    kresult                                 pylcall1  "callable", karg1, ...
    kresult1, kresult2                      pylcall2  "callable", karg1, ...
    kr1, kr2, kr3                           pylcall3  "callable", karg1, ...
    kr1, kr2, kr3, kr4                      pylcall4  "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5                 pylcall5  "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6            pylcall6  "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6, kr7       pylcall7  "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6, kr7, kr8  pylcall8   "callable", karg1, ...

                                            pylcallt   ktrigger, "callable", karg1, ...
    kresult                                 pylcall1t  ktrigger, "callable", karg1, ...
    kresult1, kresult2                      pylcall2t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3                           pylcall3t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4                      pylcall4t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5                 pylcall5t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6            pylcall6t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6, kr7       pylcall7t  ktrigger, "callable", karg1, ...
    kr1, kr2, kr3, kr4, kr5, kr6, kr7, kr8  pylcall8t  ktrigger, "callable", karg1, ...

                                            pylcalli   "callable", karg1, ...
    iresult                                 pylcall1i  "callable", iarg1, ...
    iresult1, iresult2                      pylcall2i  "callable", iarg1, ...
    ir1, ir2, ir3                           pylcall3i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4                      pylcall4i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4, ir5                 pylcall5i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4, ir5, ir6            pylcall6i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4, ir5, ir6, ir7       pylcall7i  "callable", iarg1, ...
    ir1, ir2, ir3, ir4, ir5, ir6, ir7, ir8  pylcall8i  "callable", iarg1, ...

    pylcalln   "callable", nresults, kresult1, ..., kresultn, karg1, ...
    pylcallni  "callable", nresults, iresult1, ..., iresultn, iarg1, ...

## Description

This family of opcodes call the specified Python callable at k-time and i-time (i suffix), passing the given arguments. The call is perfomed in the global environment and the result (the returning value) is copied into the Csound output variables specified.

They pass any number of parameters which are cast to float inside the Python interpreter.

The pycall/pycalli, pycall1/pycall1i ... pycall8/pycall8i opcodes can accomodate for a number of results ranging from 0 to 8 according to their numerical prefix (0 is omitted).

The pycalln/pycallni opcodes can accomodate for any number of results: the callable name is followed by the number of output arguments, then come the list of Csound output variable and the list of parameters to be passed.

The returning value of the callable must be `None` for pycall or pycalli, a float for pycall1i or pycall1i and a tuple (with proper size) of floats for the pycall2/pycall2i ... pycall8/pycall8i and pycalln/pycallni opcodes.

## Examples

Example 378. Calling a C or Python function

Supposing we have previously defined or imported a function named `get_number_from_pool` as:

    from random import random, choice

    # a pool of 100 numbers
    pool = [i ** 1.3 for i in range(100)]

    def get_number_from_pool(n, p):
        # substitute an old number with the new number?
        if random() < p:
            i = choice(range(len(pool)))
            pool[i] = n

        # return a random number from the pool
        return choice(pool)

then the following orchestra code

    k2   pycall1 "get_number_from_pool", k1, p6

would set k2 randomly from a pool of numbers changing in time. You can pass new pools elements and control the change rate from the orchestra.

Example 379. Calling a Function Object

A more generic implementation of the previous example makes use of a simple function object:

    from random import random, choice

    class GetNumberFromPool:
        def __init__(self, e, begin=0, end=100, step=1):
            self.pool = [i ** e for i in range(begin, end, step)]

        def __call__(self, n, p):
            # substitute an old number with the new number?
            if random() < p:
                i = choice(range(len(pool)))
                pool[i] = n

            # return a random number from the pool
            return choice(pool)

    get_number_from_pool1 = GetNumberFromPool(1.3)
    get_number_from_pool2 = GetNumberFromPool(1.5, 50, 250, 2)

Then the following orchestra code:

    k2   pycall1 "get_number_from_pool1", k1, p6
    k4   pycall1 "get_number_from_pool2", k3, p7

would set k2 and k3 randomly from a pool of numbers changing in time. You can pass new pools elements (here k1 and k3) and control the change rate (here p6 and p7) from the orchestra.

As you can see in the first snippet, you can customize the initialization of the pool as well as create several pools.

## Credits

Copyright (c) 2002 by Maurizio Umberto Puxeddu. All rights reserved. Portions copyright (c) 2004 and 2005 by Michael Gogins. This document has been updated Sunday 25 July 2004 and 1 February 2005 by Michael Gogins.

Prev | Up | Next
pyassign Opcodes | Home | pyeval Opcodes