{
    "info": {
        "author": "Dmitrii Torbunov",
        "author_email": "torbu001@umn.edu",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "speval\n======\nSimple Parallel Function Evaluator for python.\n\n``speval`` is a python package that allows one to easily parallelize multiple\nevaluations of some time consuming function. ``speval`` is designed to have\nno extra dependencies and be extra simple to use.\n\n\nUsage\n=====\nLet say we have a long running function ``eval_me`` and we would like to\nevaluate it 100 times, each time with different parameters. And, moreover\nperform these evaluations in parallel. We can easily achieve this with a\nsimple python script of the form:\n\n.. code-block:: python\n\n   from speval import speval\n\n   list_of_args = [\n      args_for_eval1,\n      args_for_eval2,\n      ...\n      args_for_eval100,\n   ]\n\n   speval(eval_me, list_of_args, db_name)\n\nNow, we can run one instance of this script and it will start evaluating\nfunction ``eval_me`` for each point of ``list_of_args``. To parallelize\nevaluations we just need to run another ``N`` instances of this script, and\nthey are going to distribute evaluations of ``eval_me`` among them, using\nsqlite3 database ``db_name`` for synchronization.\n\nOnce all evaluations are complete we can use function ``load_evals`` to\nretrieve results(if any) of each evaluation from the database ``db_name``.\n\n\nMotivation\n==========\n``speval`` was written because the author needed a simple hyperparameter\noptimization package without heavy dependencies(like ``mongodb``), or need to\nproperly set up workers on multiple machines.\n\n\nRequirements\n============\n``python-3`` built with sqlite3 support(enabled by default)\n\n\nExamples\n========\n\nA number of examples is stored in the ``examples`` subdirectory. Here is a\nbrief overview of them.\n\n01. Hello World\n---------------\nLet's start with a primitive function to evaluate\n\n.. code-block:: python\n\n   import time\n\n   def func(arg):\n       print(\"Hello world: %d\" % (arg))\n       time.sleep(2)\n\nSay we want to evaluate function ``func`` 100 times using evaluation index as\nan argument to ``func``. To perform this we first need to define a list with\narguments for each evaluation\n\n.. code-block:: python\n\n   eval_space = list(range(100))\n\nAnd then call ``speval``\n\n.. code-block:: python\n\n   from speval import speval\n\n   speval(func, eval_space, \"/tmp/01_hello_world.db\", timeout = 60)\n\nHere we see that ``speval`` takes function to evaluate ``func`` as a first\nargument, list with arguments for each evaluation ``eval_space`` as a second\nargument. We also pass there a sqlite database file name\n(``\"/tmp/01_hello_world.db\"``) which will be used for coordination between\ndifferent processes. And a ``timeout`` parameter which tells ``speval`` that a\ngiven evaluation of function ``func`` has failed if it was not completed in 60\nseconds and therefore needs to be restarted.\n\nDone. Now we can run the resulting script(e.g. ``examples/01_hello_world.py``)\nas many times in parallel as many jobs we want to allocate for the task of\nprinting \"Hello world\".\n\nFor example, on a unix system one may run in a terminal\n\n.. code-block:: console\n\n   $ python examples/01_hello_world.py\n   Hello world: 0\n   Hello world: 1\n   Hello world: 2\n   Hello world: 3\n   Hello world: 4\n   ...\n\nSo, it will print ``\"Hello world: N\"`` each 2 seconds, and without further\nintervention will finish in about 200 seconds. To parallelize printing\nwe can run another say 20 jobs in a separate terminal. E.g.\n\n.. code-block:: console\n\n   $ for i in {1..20}; do (python examples/01_hello_world.py &) ; done\n\nNow, all pending hello worlds will be printed in just about 10 seconds.\n\n\n02. Storing/Retrieving Function Results\n---------------------------------------\n\nIn ``examples`` directory there are 2 scripts ``02_store_results.py`` and\n``02_retrieve_results.py``. First script is just a modification of the hello\nworld example, where function ``func`` also returns a value, which is\nautomatically stored in the database. Second script there is used to\ndemonstrate how to retrieve saved results from the database.\n\n\n03. Using speval for Hyperparameter Optimization\n------------------------------------------------\n\nFinally, there are another 2 examples ``03_fit_line.py`` and\n``03_get_best_fit.py``, which demonstrate how to use ``speval`` for\nhyperparameter optimization over a predefined search space(grid search or\nrandomized search). Here the first script evaluates objective function on each\npoint of the search space. This script can be run on the multiple machines in\nparallel, provided they all have access to a shared mount on which a sqlite3\ndatabase resides.\n\nThe second script is can be used to find optimal values of hyperparameters from\nthe results of these evaluations stored in the database.\n\n\nLimitations\n===========\n\n``speval`` uses sqlite3 internal advisory file locking mechanism to prevent\nrace conditions. This mechanism is known not to work properly for some network\nfilesystem `setups`__. So be advised if your database is on NFS mount.\n\nAdditionally, ``speval`` relies on json format to serialize parameters. So,\nyou need to make sure that ``eval_space`` and results returned by the\n``eval_func`` are json serializable objects.\n\n.. _sqlite_locking: https://www.sqlite.org/lockingv3.html#how_to_corrupt\n__ sqlite_locking_",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/usert5432/speval",
        "keywords": "",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "speval",
        "package_url": "https://pypi.org/project/speval/",
        "platform": "",
        "project_url": "https://pypi.org/project/speval/",
        "project_urls": {
            "Homepage": "https://github.com/usert5432/speval"
        },
        "release_url": "https://pypi.org/project/speval/0.1.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Simple Parellel Function Evaluator",
        "version": "0.1.1"
    },
    "last_serial": 4936588,
    "releases": {
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "fa9fe8b11f55510ad217b17caeda0dc1",
                    "sha256": "a2a870f2d9ba28aa2b533f57fbc851f556057002fda3ab5bc49943fa1dd81807"
                },
                "downloads": -1,
                "filename": "speval-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "fa9fe8b11f55510ad217b17caeda0dc1",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 8101,
                "upload_time": "2019-03-13T21:35:58",
                "url": "https://files.pythonhosted.org/packages/50/e5/224813209bebded7f52dfe31b91b071d03132da7f80b979889fa43fe2cb5/speval-0.1.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "fa9fe8b11f55510ad217b17caeda0dc1",
                "sha256": "a2a870f2d9ba28aa2b533f57fbc851f556057002fda3ab5bc49943fa1dd81807"
            },
            "downloads": -1,
            "filename": "speval-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "fa9fe8b11f55510ad217b17caeda0dc1",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 8101,
            "upload_time": "2019-03-13T21:35:58",
            "url": "https://files.pythonhosted.org/packages/50/e5/224813209bebded7f52dfe31b91b071d03132da7f80b979889fa43fe2cb5/speval-0.1.1.tar.gz"
        }
    ]
}