{
    "info": {
        "author": "Gregory Parkes",
        "author_email": "g.m.parkes@soton.ac.uk",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Framework :: IPython",
            "Framework :: Jupyter",
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
            "Natural Language :: English",
            "Programming Language :: Python :: 3.7",
            "Topic :: Scientific/Engineering"
        ],
        "description": "# battlesim: Modelling and animating simulated battles between units in Python.\n\nThe aim of this side project is to become familiar with Python classes and with primitive forms of animation and simulating environments. We map units onto a 2D plane and run simple simulations that involve them moving towards an enemy unit and attacking it. Rounds finish when one team has completely wiped out the other side, or we have reached the maximum number of timesteps.\n\n**Current version: 0.3.5**\n\n![Image not found](simulations/sim2.gif)\n\nThe code for the primary engine is found in `battlesim/`, and implementations/examples are found in the Jupyter notebooks. Animations should display properly in these notebooks.\n\n## Installation\n\n`battlesim` requires the following dependencies:\n\n* Python (>=3.5)\n* NumPy (>=1.11.0)\n* SciPy (>=1.3)\n* Pandas (>=0.25.1)\n* Matplotlib (>=3.1.1)\n* Numba (>=0.45)\n\nWith the following for exporting the animation as a gif:\n\n* ffmpeg\n\n### From PyPI\n\nIf you have working versions of the dependencies, similarly install using `pip`:\n\n```bash\npip install battlesim\n```\n\nWe recommend updating the dependencies yourself using conda rather than through pip because conda manages the dependencies better, but pip will do it for you. See the `environment.yml` file for dependencies.\n\n### From Cloning the GitHub Repository\n\nAlternatively if you are cloning this GitHub repository, use:\n\n```bash\ngit clone https://github.com/gregparkes/BattleSimulator\nconda env create -f environment.yml\nconda activate bsm\n```\n\nNow within the `bsm` environment run your Jupyter notebook:\n\n```bash\njupyter notebook\n```\n\n### Running Tests\n\nYou will need the following for testing (soft requirement):\n\n* PyTest (5.1.2)\n\nThen perform the following within a console:\n\n```bash\ncd tests/\npytest -v\n```\n\n## How to use: The Basics\n\nFirstly, check the requirements for using this simulator, of which most come with the **Anaconda** distribution. In addition you will need the **ffmpeg** video conversion package to generate the simulations as animations.\n\nSecondly, you will need to import the package as:\n\n```python\n>>> import battlesim as bsm\n```\n\nWe recommend using `bsm` as a shorthand to reduce the amount of writing out you have to do. If you're using Jupyter notebook we also recommend:\n\n```python\n>>> import matplotlib.pyplot as plt\n>>> plt.rcParams[\"animation.html\"] = \"html5\"\n>>> %matplotlib inline\n```\n\nThe second line is important when you come to plotting the animations, as there are a number of issues with using it. All of the heavy lifting comes in the `bsm.Battle` object that provides a neat interface for all of the operations you would like to conduct:\n\n```python\n>>> import battlesim as bsm\n>>> battle = bsm.Battle(\"datasets/starwars-clonewars.csv\")\n>>> battle\nbsm.Battle(init=False)\n```\n\nYou can see that we have specified a 'dataset' from which all of the unit roster can be drawn from; for specifics of how this file should\nbe oriented, see the documentation. We then need to specify units to create to form an army. For example, in this Star Wars example, we could specify a play-off between Clone troopers and B1 battledroids:\n\n```python\n>>> battle.create_army([(\"B1 battledroid\", 70), (\"Clone Trooper\", 50)])\nbsm.Battle(init=True, n_armies=2, simulated=False)\n```\n\nHere we call the `create_army` function, which internally creates an efficient `numpy` matrix, ready to perform the simulation. This is stored in the `battle.M_` object, a heterogenous `ndarray` element. From here, we might also want to specify the locations of our different blobs, as by default they will be sitting on top of each other at (0, 0).\n\n```python\n>>> battle.apply_position([dict(name=\"normal\", x_loc=10), dict(name=\"normal\", loc=0)])\nbsm.Battle(init=True, n_armies=2, simulated=False)\n```\n\nHere the first element of each tuple represents the mean of the gaussian distribution, and the second element refers to the variance (or spread). From here, all we need to do now is simulate this:\n\n```python\n>>> F = battle.simulate()\n```\n\nBy default, the simulation function will make a record of important parameters at each step and then return these parameters as a `pandas.DataFrame` at the end in *long form* (with a cached element called `sim_`). In addition, because you want to see what's going on - we can animate the frames using this convenience method within the battle object:\n\n```python\n>>> battle.sim_jupyter()\n```\n\n![Image not found](simulations/sim1.gif)\n\nHere `sim_jupyter` treats each unit object as a quiver arrow in 2-d space (position and direction facing it's enemy). The targets should move towards each other and attempt to kill each other. Dead units are represented as crosses **'x'** on the map. \n\n![Image not found](images/quiver2.svg)\n\nThe rest is for you to explore, tweak and enjoy watching arrows move towards each other and kill each other.\n\n## One step further: Repeated runs\n\nIf you're interested in seeing how each team fare over multiple runs (to eliminate random biases), then `bsm.Battle` objects once defined, contain a `simulate_k()` method, where `k` specifies the number of runs you wish to complete. Unlike `simulate()` by itself, it does not return a `pandas.DataFrame` of frames, but rather the number of units from each team left standing at each iteration.\n\n```python\n>>> runs = battle.simulate_k(k=40)\n```\n\nThis is the beginning of creating an interface similar to Machine Learning, whereby the outcome can be a classification (team) or regression (number of units surviving) target, and the unit compositions, aspects of the engine etc., can be inputs.\n\n## New in 0.3.5\n\nThere are a number of exciting changes in this current update, including:\n\n- Introduction of **Terrains**. This is a major expansion giving 3D pseudodepth to animated battles. Depth now influences movement speed of units, with terrain penalties applied (up to 50%) on higher hills.\n- Boundary checking for units\n- Many internal bug fixes\n- Provided `pip` support\n\n## Teaching series\n\nAs well as a fully-fledged package simulator, you can find teaching material in Jupyter notebook form within the `teaching/` subfolder, that takes users through the development process of this package, compares and contrasts Object-Oriented (OO) implementations to numpy-esque implementations, their performance, plotting, animations and more. We hope you find this material interesting and will aid as you use the package and possibly develop packages of your own in the future.\n\nMaterial covered so far:\n\n1. Basics, including importing the dataset, the `Unit` class, basic simulation\n2. Improving the `Unit` class and simulation early-stopping for performance.\n3. Plotting simulations and performance-driven development\n\nThis is still in active development retracing the steps of the project. All legacy functions associated with this can be found in the `battlesim/legacy.py` document.\n\n## Future plans\n\n* Include AI-based behavior that makes use of height (to occupy hills)\n* Develop 'defensive' AI.\n* Build objects in the terrain.\n\n***\n\nEnsure that any use of this material is appropriately referenced and in compliance with the license.\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/gregparkes/battlesim",
        "keywords": "",
        "license": "GPL-3.0",
        "maintainer": "",
        "maintainer_email": "",
        "name": "battlesim",
        "package_url": "https://pypi.org/project/battlesim/",
        "platform": "",
        "project_url": "https://pypi.org/project/battlesim/",
        "project_urls": {
            "Homepage": "https://github.com/gregparkes/battlesim"
        },
        "release_url": "https://pypi.org/project/battlesim/0.3.5/",
        "requires_dist": [
            "numpy (>=1.11.0)",
            "scipy (>=1.3)",
            "pandas (>=0.25.1)",
            "matplotlib (>=3.1.1)",
            "numba (>=0.45)"
        ],
        "requires_python": ">=3.6",
        "summary": "A python package for simulating battles and visualizing them in animation",
        "version": "0.3.5"
    },
    "last_serial": 5978182,
    "releases": {
        "0.3.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "01087198f8f0a9f518454acf31bb1f92",
                    "sha256": "c49ea51c5c06e87e58887e33cd1df6ef59caf7b1e06ba937f381942bcf45dc73"
                },
                "downloads": -1,
                "filename": "battlesim-0.3.5-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "01087198f8f0a9f518454acf31bb1f92",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.6",
                "size": 49175,
                "upload_time": "2019-10-15T16:03:08",
                "url": "https://files.pythonhosted.org/packages/ce/ea/a799f00c77b9d50f16e7a6deb490102e8d1edb989f2432183b0c840cdf5d/battlesim-0.3.5-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "29d752b6a8188d73c42c8985e6006c8a",
                    "sha256": "41152744a8173acbf1bca8dcb73ef162bd35e629aeac4c5168809c6ceae6c167"
                },
                "downloads": -1,
                "filename": "battlesim-0.3.5.tar.gz",
                "has_sig": false,
                "md5_digest": "29d752b6a8188d73c42c8985e6006c8a",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6",
                "size": 33364,
                "upload_time": "2019-10-15T16:03:11",
                "url": "https://files.pythonhosted.org/packages/4c/53/5c6ccd2e81c1aa10bd14611773c9c3ca7eb687b87740e3188c339c5e592d/battlesim-0.3.5.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "01087198f8f0a9f518454acf31bb1f92",
                "sha256": "c49ea51c5c06e87e58887e33cd1df6ef59caf7b1e06ba937f381942bcf45dc73"
            },
            "downloads": -1,
            "filename": "battlesim-0.3.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "01087198f8f0a9f518454acf31bb1f92",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 49175,
            "upload_time": "2019-10-15T16:03:08",
            "url": "https://files.pythonhosted.org/packages/ce/ea/a799f00c77b9d50f16e7a6deb490102e8d1edb989f2432183b0c840cdf5d/battlesim-0.3.5-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "29d752b6a8188d73c42c8985e6006c8a",
                "sha256": "41152744a8173acbf1bca8dcb73ef162bd35e629aeac4c5168809c6ceae6c167"
            },
            "downloads": -1,
            "filename": "battlesim-0.3.5.tar.gz",
            "has_sig": false,
            "md5_digest": "29d752b6a8188d73c42c8985e6006c8a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 33364,
            "upload_time": "2019-10-15T16:03:11",
            "url": "https://files.pythonhosted.org/packages/4c/53/5c6ccd2e81c1aa10bd14611773c9c3ca7eb687b87740e3188c339c5e592d/battlesim-0.3.5.tar.gz"
        }
    ]
}