multijob.job module

Create jobs in various configurations and run them.

The JobBuilder class lets you build a combination of parameters easily. It produces a list of Job instances. When running a job, you get a JobResult.

class multijob.job.Job(job_id, repetition_id, callback, params)

Bases: object

A concrete, runnable set of configuration parameters.

Do not create directly – use JobBuilder instead!

Parameters:

• job_id – identify this set of parameters
• repetition_id – distinguish repetitions of this set of parameters
• callback – function to invoke with params
• params (dict) – the parameters

job_id

Identifies this set of parameters

params

dict – The chosen set of parameters. Do not modify.

repetition_id

Distinguishes repetitions of this set of parameters.

run()

Execute the job.

Returns:the callback result, wrapped in a JobResult. Return type:JobResult

Example:

>>> def add(x, y): return x + y
>>> job = Job(1, 2, add, dict(x=2, y=40))
>>> result = job.run()
>>> result.job is job
True
>>> result.result
42

class multijob.job.JobBuilder(**defaults)

Bases: object

Create a range of jobs to cover the required parameter combinations

Parameters:defaults – any default values for the parameters

add(param, *values)

Add a specific range of parameters.

Parameters:

• param – the name of the parameter
• values – The values you want to add

Returns:

The added values.

Example:

>>> builder = JobBuilder()
>>> builder.add('x', 1, 2, 3)
(1, 2, 3)

Example: Redefinition of a parameter is impossible:

>>> builder = JobBuilder()
>>> builder.add('x', 1, 2, 3)
(1, 2, 3)
>>> builder.add('x', 4, 5, 6)
Traceback (most recent call last):
RuntimeError: redefinition of parameter 'x'

add_linspace(param, start, stop, num)

Create a [start, stop] inclusive range of floats.

Parameters:

• param (str) – The name of the param to add.
• start (float) – The start of the range.
• stop (float) – The inclusive stop of the range.
• num (int) – The number of items in the range, must be at least 2.

Returns:

The added items.

Example:

>>> builder = JobBuilder()
>>> builder.add_linspace('x', 2, 5, 7)
[2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0]

Example:

>>> builder = JobBuilder()
>>> expected = [0.0, 1/3, 2/3, 1.0, 4/3, 5/3, 2.0]
>>> actual = builder.add_linspace('x', 0, 2, 7)
>>> actual == expected or (actual, expected)
True

Example: start must be smaller than stop:

>>> builder = JobBuilder()
>>> builder.add_linspace('x', 3, 0, 7)
Traceback (most recent call last):
ValueError: start must be smaller than stop

Example: num must be at least 2 to include start and stop:

>>> builder = JobBuilder()
>>> builder.add_linspace('x', 0, 3, 1)
Traceback (most recent call last):
ValueError: num must be at least 2 to include the start and stop

add_range(param, start, end, stride)

Create a [start, end] inclusive range of floats.

Parameters:

• param (str) – The name of the param to add.
• start (float) – The start of the range.
• end (float) – The inclusive end of the range. This might not be included if (end - start)/stride is not integer.
• stride (float) – The step size between numbers in the range.

Returns:

The added values.

Example:

>>> builder = JobBuilder()
>>> builder.add_range('x', 2, 5, 0.5)
[2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0]

Example:

>>> def round_all(ndigits, xs):
...     return [round(x, ndigits) for x in xs]
>>> builder = JobBuilder()
>>> expected = round_all(7, [0/3, 1/3, 2/3, 3/3, 4/3, 5/3, 6/3])
>>> actual = round_all(7, builder.add_range('x', 0, 2, 1/3))
>>> actual == expected or (actual, expected)
True

Example: start must be smaller than end:

>>> builder = JobBuilder()
>>> builder.add_range('x', 3, 0, 0.5)
Traceback (most recent call last):
ValueError: start must be smaller than end

Example: stride must be positive:

>>> builder = JobBuilder()
>>> builder.add_range('x', 0, 3, -0.5)
Traceback (most recent call last):
ValueError: stride must be positive

build(callback, repetitions=1)

Create all Job objects from this configuration.

Parameters:

• callback – The function to invoke in the Job.
• repetitions – How often each parameter set should be repeated.

Returns:

All job objects.

Return type:

List[Job]

Example:

>>> def target(x, y, z): pass
>>> builder = JobBuilder(x=2)
>>> builder.add('y', 1, 2, 3)
(...)
>>> builder.add('z', True, False)
(...)
>>> jobs = builder.build(target, 2)
>>> jobs
[<multijob.job.Job object at 0x...>, ...]
>>> for job in jobs:
...     print(job)
0:0: x=2 y=1 z=True
0:1: x=2 y=1 z=True
1:0: x=2 y=1 z=False
1:1: x=2 y=1 z=False
2:0: x=2 y=2 z=True
2:1: x=2 y=2 z=True
3:0: x=2 y=2 z=False
3:1: x=2 y=2 z=False
4:0: x=2 y=3 z=True
4:1: x=2 y=3 z=True
5:0: x=2 y=3 z=False
5:1: x=2 y=3 z=False

Example: empty config still produces a configuration:

>>> def target(): pass
>>> builder = JobBuilder()
>>> builder.build(target, 2)
[<...>, <...>]

Example: the callback must be callable:

>>> builder = JobBuilder()
>>> builder.build("target", 2)
Traceback (most recent call last):
TypeError: callback must be callable

Example: at least one repetition required:

>>> def target(): pass
>>> builder = JobBuilder()
>>> builder.build(target, 0)
Traceback (most recent call last):
ValueError: at least one repetition required

number_of_jobs()

Calculate the number of jobs that will be generated.

Example:

>>> builder = JobBuilder()
>>> builder.number_of_jobs()
1
>>> builder.add('a', 7)
(...)
>>> builder.add('b', 1, 2, 3)
(...)
>>> builder.add('c', 'a', 'b', 'c', 'd')
(...)
>>> builder.number_of_jobs()
12

class multijob.job.JobResult(job, result)

Bases: object

The result of a job execution.

job

Job – The job that was run to generate this result.

result

Whatever the job callback returned.