Windows parallelisation doesn't work out of the box

[lenarddome]

Parallel computing on Windows

Issue#16 is a known issue with Windows and parallelisation.
The way to circumvent this is to wrap your code in into if __name__ == '__main__': and load the parallelised optimisation bits as separate modules.

Walktrhough for Jupyter

In principle, you only need to wrap the code chunk were you fit to data in a fashion similar to this:

## Windows/macOS only: prevents workers from spawning more workers
## when the script is re-imported at startup
if __name__ == "__main__":
    ## specify the dependent variable we use for the log-likelihoods
    ## DataFrame["new_col"] = ... is the idiomatic way to create/overwrite a column
    two_armed_bandit_dataset["observed"] = two_armed_bandit_dataset["response"]
    ## initialise the optimisation method
    fit = FminBound(
        model=generative, ## the wrapper we created before
        # pandas .groupby('ppt') creates one data block per participant
        data=two_armed_bandit_dataset.groupby('ppt'), ## each group is a participant
        minimisation=minimise.LogLikelihood.bernoulli, ## the loss or discrepency function
        parallel=True, ## booleans as keyword flags toggle behaviour
        cl=4, ## the number of cores to use
        prior=False, ## whether to use priors in the loss function
        display=False, ## whether to quiet the output
        number_of_starts=2, ## starting points for the gradient descents
        libraries=["numpy", "pandas", "cpm"], ## list literal passed by keyword
        # everything below is optional and passed directly to
        # the scipy implementation of the optimiser
        approx_grad=True
    )
    ## run the optimisation
    fit.optimise()
    ## export the optimisation results
    optimization_results = fit.export()

Walkthrough for using python scripts

Assume that you have the following folder structure:

```bash
project_name/
├── docs/
│   ├── lab_report.ipynb
│   └── data/
│       └── big_data_file.csv
├── src/
│   ├── main.py
│   └── utils/
│       ├── __init__.py
│       ├── setup_model.py
│       └── fitting.py
└── README.md

Feel free to adjust this structure based on your specific project needs.
fitting.py and setup_model.py are the files that contain the fitting and model setup functions, respectively.

For setup_model.py, you can structure it as follows:

def model_setup(data):
    """
    The following function sets up the model.

    Parameters
    ----------
    data : list
        The data as a list of dictionaries.

    Return
    ------
    parameters : cpm.generators.Parameters
        The parameter object for the model
    wrapper : cpm.generators.Wrapper
        The Wrapper object with the model specified below.
    """

    from cpm.models import learning, decision
    from cpm.generators import Value, Parameters, Wrapper
    import numpy as np

    parameters = Parameters(
        # ... your parameters here
    )

    def model(parameters, trial):
        # ... your model code here
        return output

    wrapper = Wrapper(model=model, parameters=parameters, data=data)

    print(wrapper)

    return parameters, wrapper

Your fitting.py file can be structured as follows:

def fitting(wrapper, experiment):
    """
    The following function is used to fit the model to the data using the Differential Evolution algorithm. The function also saves the optimisation data and the simulation data as .csv files.

    Parameters
    ----------
    wrapper : cpm.generators.Wrapper
        The wrapper class with the model we specified from before.
    experiment : list
        The data as a list of dictionaries.

    Returns
    -------
    data : pandas.DataFrame
        The optimisation data.
    """

    from cpm.optimisation import minimise, DifferentialEvolution
    from cpm.generators import Wrapper, Simulator, Parameters
    import pickle as pkl

    genetic = DifferentialEvolution(
        model=wrapper,  # Wrapper class with the model we specified from before
        data=experiment,  # the data as a list of dictionaries
        minimisation=minimise.LogLikelihood.bernoulli,
        # ... additional arguments go here
    )

    genetic.optimise()

    data = genetic.export()
    data.to_csv("optimisation.csv", index=False) # make sure to save stuff

    simulation = Simulator(
        wrapper=wrapper, parameters=genetic.parameters, data=experiment
    )
    simulation.run()

    simulation_data = simulation.export()
    simulation_data.to_csv("simulation.csv", index=False) # make sure to save stuff

    return data

The important part is that you have a main.py file that will be the entry point for your project.
You can structure your main.py as follows:

if __name__ == "__main__":
    import sys
    import os
    import time
    import pandas as pd

    # get the directory of the current file, and add to sys.path if necessary
    current_dir = os.path.dirname(os.path.abspath(__file__))
    if current_dir not in sys.path:
        sys.path.append(current_dir)

    print("Importing data")

    file_path = r"some_data_file.csv"

    experiment = pd.read_csv(file_path)

    ###################################
    ###### your code goes here ########
    ###################################

    from utils.model import model_setup
    from utils.fitting import fitting

    print("\nSetting up model")
    # model_setup is a function that returns a cpm.generators.Parameters and a cpm.generators.Wrapper object
    parameters, learning_model = model_setup(experiment[ppt==1])

    # time to fit the model
    start = time.time()

    print(f"\n {start} : Fitting model")
    # fitting is a function that returns a pandas dataframe with the fitted parameters and other information
    output = fitting(learning_model, environment)
    end = time.time()
    print(f"\n {end} : Model fitted in {end - start} seconds")

If you have this sorted, you can execute the main.py file from the command line as well, and the parallelisation should work as expected.

python src/main.py