Package: deepcomp
DeepCoMP: Self-Learning Dynamic Multi-Cell Selection for Coordinated Multipoint (CoMP)Multi-Agent Deep Reinforcement Learning for Coordinated Multipoint in Mobile NetworksThree variants: DeepCoMP (central agent), DD-CoMP (distributed agents using central policy), D3-CoMP (distributed agents with separate policies).
All three approaches self-learn and adapt to various scenarios in mobile networks without expert knowledge, human intervention, or detailed assumptions about the underlying system.
Compared to other approaches, they are more flexible and achieve higher Quality of Experience.For a high-level overview of DeepCoMP, please refer to myblog post.
More details are available in our research paper presenting DeepCoMP (preprint).
I also talked about DeepCoMP at the Ray Summit 2021 (YouTube).The simulation environment used to train DeepCoMP is available separately asmobile-env.Visualized cell selection policy of DeepCoMP after 2M training steps.Base station iconby Clea Doltz from the Noun ProjectCitationIf you use this code, please cite ourpaper (preprint; accepted at IEEE TNSM 2023):@article{schneider2023deepcomp,
	title={Multi-Agent Deep Reinforcement Learning for Coordinated Multipoint in Mobile Networks},
	author={Schneider, Stefan and Karl, Holger and Khalili, Ramin and Hecker, Artur},
	journal={IEEE Transactions on Network and Service Management (TNSM)},
	year={2023},
}SetupYou need Python 3.8+. You can installdeepcompeither directly fromPyPior manually after cloning this repository.Simple Installation via PyPisudo apt update
sudo apt upgrade
sudo apt install cmake build-essential zlib1g-dev python3-dev

pip install deepcompManual Installation from SourceFor adjusting or further developing DeepCoMP, it's better to install manually rather than from PyPi.
Clone the repository. Then install everything, following these steps:# only on ubuntu
sudo apt update
sudo apt upgrade
sudo apt install cmake build-essential zlib1g-dev python3-dev

# clone
git clone git@github.com:CN-UPB/DeepCoMP.git
cd DeepCoMP

# install all python dependencies
pip install .
# "python setup.py install" does not work for some reason: https://stackoverflow.com/a/66267232/2745116
# for development install (when changing code): pip install -e .Tested on Ubuntu 20.04 and Windows 10 with Python 3.8.For saving videos and gifs, you also need to install ffmpeg (not on Windows) andImageMagick.
On Ubuntu:sudo apt install ffmpeg imagemagickDockerThere is a Docker image that comes withdeepcomppreinstalled.
To use the Docker image, simply pull the latest version fromDocker Hub:docker pull stefanbschneider/deepcomp
# tag image with just "deepcomp". alternatively, write out "stefanbschneider/deepcomp" in all following commands.
docker tag stefanbschneider/deepcomp:latest deepcompAlternatively, to build the Docker image manually from theDockerfile, clone this repository and rundocker build -t deepcomp .Use the--no-cacheoption is to force a rebuild of the image, pulling the latestdeepcompversion from PyPI.Usage# get an overview of all options
deepcomp -hFor example:deepcomp --env medium --slow-ues 3 --agent central --workers 2 --train-steps 50000 --seed 42 --video bothTo run DeepCoMP, use--alg ppo --agent central.
For DD-CoMP, use--alg ppo --agent multi, and for D3-CoMP, use--alg ppo --agent multi --separate-agent-nns.By default, training logs, results, videos, and trained agents are saved in<project-root>/results,
where<project-root>is the root directory of DeepCoMP.
If you cloned the repo from GitHub, this is where the Readme is.
If you installed via PyPi, this is in your virtualenv's site packages.
You can choose a custom location with--result-dir <custom-path>.DockerNote:By default, results within the Docker container are not stored persistently.
To save them, copy them from the Docker container or use a Docker volume.Start the ContainerIf you want to use thedeepcompDocker container and pulled the corresponding image from Docker Hub,
you can use it as follows:docker run -d -p 6006:6006 -p 8000:8000 --rm --shm-size=3gb --name deepcomp deepcompThis starts the Docker container in the background, publishing port 6006 for TensorBoard and port 8000 for the
HTTP server (described below).
The container automatically starts TensorBoard and the HTTP server, so this does not need to be done manually.
The--rmflag automatically removes the container once it is stopped.
The--shm-size=3gbsets the size of/dev/shminside the Docker container to 3 GB, which is too small by default.Use DeepCoMP on the ContainerTo execute commands on the running Docker container, usedocker exec <container-name> <command>as follows:docker exec deepcomp deepcomp <deepcomp-args>Here, the arguments are identical with the ones described above.
For example, the following command lists all CLI options:docker exec deepcomp deepcomp -hOr to train the central DeepCoMP agent for a short duration of 4000 steps:docker exec -t deepcomp deepcomp --approach deepcomp --train-steps 4000 --batch-size 200 --ues 2 --result-dir resultsImportant:Specify--result-dir resultsas argument.
Otherwise, the results will be stored elsewhere and TensorFlow and the HTTP server will not find and display them.The otherdeepcomparguments can be set as desired.
The Docker-tflag ensures that the output is printed continuously during training, not just after completion.To inspect training progress or view create files (e.g., rendered videos), use TensorBoard and the HTTP server,
which are available vialocalhost:6006andlocalhost:8000.Terminate the ContainerImportant:Stopping the container will remove any files and training progress within the container.Stop the container withdocker stop deepcompAccessing results remotelyWhen running remotely, you can serve the replay video by running:cd results
python -m http.serverThen access at<remote-ip>:8000.TensorboardTo view learning curves (and other metrics) when training an agent, use Tensorboard:tensorboard --logdir results/train/ (--host 0.0.0.0)Tensorboard is available athttp://localhost:6006(or<remote-ip>:6006when running remotely).Scaling Up: Running DeepCoMP on multiple cores or a multi-node clusterTo train DeepCoMP on multiple cores in parallel, configure the number of workers (corresponding to CPU cores) with--workers.To scale training to a multi-node cluster, adjustcluster.yamland follow the steps describedhere.
Set--workersto the total number of CPU cores you want to use on the entire cluster.DocumentationAPI documentation is onhttps://cn-upb.github.io/DeepCoMP/.Documentation is generated based on docstrings usingpdoc3:# from project root
pip install pdoc3
pdoc --force --html --output-dir docs deepcomp
# move files to be picked up by GitHub pages
mv docs/deepcomp/ docs/
# then manually adjust index.html to link to GitHub repoContributionsDevelopment:@stefanbschneiderFeature requests, questions, issues, and pull requests via GitHub are welcome.AcknowledgementDeepCoMP is an outcome of a joint project between Paderborn University, Germany, and Huawei Germany.Base station icon(used in rendered videos) by Clea Doltz from the Noun Project.