{"id":15707824,"url":"https://github.com/mthrok/luchador","last_synced_at":"2026-03-01T23:03:00.571Z","repository":{"id":91656180,"uuid":"58234240","full_name":"mthrok/luchador","owner":"mthrok","description":"Toolkit for [Deep] Reinforcement Learning","archived":false,"fork":false,"pushed_at":"2017-07-29T19:49:41.000Z","size":87238,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-12T19:58:53.315Z","etag":null,"topics":["deep-learning","dqn","neural-network","reinforcement-learning","tensorflow","theano"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mthrok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-06T20:52:08.000Z","updated_at":"2022-12-02T12:34:18.000Z","dependencies_parsed_at":"2024-05-12T02:01:19.680Z","dependency_job_id":null,"html_url":"https://github.com/mthrok/luchador","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/mthrok/luchador","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthrok%2Fluchador","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthrok%2Fluchador/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthrok%2Fluchador/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthrok%2Fluchador/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mthrok","download_url":"https://codeload.github.com/mthrok/luchador/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthrok%2Fluchador/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29987656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T22:42:38.399Z","status":"ssl_error","status_checked_at":"2026-03-01T22:41:51.863Z","response_time":124,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","dqn","neural-network","reinforcement-learning","tensorflow","theano"],"created_at":"2024-10-03T20:41:28.824Z","updated_at":"2026-03-01T23:02:55.561Z","avatar_url":"https://github.com/mthrok.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Codacy Badge](https://api.codacy.com/project/badge/Grade/7c1de2718e594da09513074a6c7b1c0e)](https://www.codacy.com/app/mthrok/luchador?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=mthrok/luchador\u0026amp;utm_campaign=Badge_Grade)\n[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/7c1de2718e594da09513074a6c7b1c0e)](https://www.codacy.com/app/mthrok/luchador?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=mthrok/luchador\u0026amp;utm_campaign=Badge_Coverage)\n\n\n## Overview\n\nLuchador is a library for Deep Learning built on top of Tensorflow or Theano. You can build complex network using configuration file like Caffe, but with simpler YAML format.\n\n\n### Build network from configuration file\n\nIn luchador, network components can be instantiated with python-primitive-type arguments (such as `number`, `string`, `list`, and `dict`), thus, just by giving the class name you want to instantiate (as `typename`) and its arguments (as `args`), the network can be built.\n\nThe following configuration file defines sequential network composed of convolution and non-linear activation followed by inner product.\n\n```yaml\ntypename: Sequential\nargs:\n  name: classifier\n  input_config:\n    typename: Input\n    name: input_image\n    shape: [32, 84, 84, 1]\n  layer_configs:\n    - typename: Conv2D\n      args:\n        n_filters: 32\n        filter_width: 8\n        filter_height: 8\n        strides: 4\n        padding: valid\n    - typename: ReLU\n    - typename: Flatten\n    - typename: Dense\n      args:\n        n_nodes: 10\n```\n\nYou can construct the model with `luchador.nn.make_model` function as following.\n\n```python\nimport numpy as np\nimport luchador\nimport luchador.nn as nn\n\nmodel_config = nn.get_model_config('model.yml')\nmodel = nn.make_model(model_config)\n```\n\nThis will create the following network. (To visualize network, you need to run luchador with Tensorflow backend. See [Setting Backend](#setting-backend) for this.)\n\n\u003cimg src=\"assets/network_01.png\" width=\"280\"\u003e\n\nFor executing computation, luchador provides `Session` interface which works in a similar way as Tensorflow sesison.\n\n```python\nsession = nn.Session()\nsession.initialize()\n\ninput_shape = [32, 84, 84, 1]\ninput_data = np.random.rand(*input_shape)\noutput_data = session.run(\n    inputs={\n        model.input: input_data,\n    },\n    outputs=model.output,\n)\n```\n\n\n### Parameterize network structure\n\nBut fixing parameters is often inconvenient. You can put placeholder with `{placeholder_name}` in model YAML file and give value at runtime, by giving value to `get_model_config`.\n\nIn the following example, network input shape (`input_shape`) is set at runtime. At runtime, the code checks the current backend to define image channel order accordingly. (`NHWC` for Thensorflow CPU, `NCHW` for the others.)\n\n```yaml\ntypename: Sequential\nargs:\n  name: classifier\n  input_config:\n    typename: Input\n    args:\n      name: input_image\n      shape: {input_shape}\n  layer_configs:\n    - typename: Conv2D\n      args:\n        n_filters: 32\n        filter_width: 8\n        filter_height: 8\n        strides: 4\n        padding: valid\n    - typename: ReLU\n    - typename: Flatten\n    - typename: Dense\n      args:\n        n_nodes: 10\n```\n\n```python\nbe = luchador.get_nn_backend()\nfmt = luchador.get_nn_conv_format()\nif be == 'tensorflow' and fmt == 'NHWC':\n    input_shape = [32, 84, 84, 1]\nelse:\n    input_shape = [32, 1, 84, 84]\n\nmodel_config = nn.get_model_config('model.yml', input_shape=input_shape)\nmodel = nn.make_model(model_config)\n```\n\n\n### Complex networks\n\nIn the sense of computation node, Sequential model represents one-to-one mapping. To build more complex graph, one needs to create many-to-many mappings. In luchador you can use `Graph` and `Container` models and feed compound input object to build such network.\n\n\n#### Commpound input\n\nLuchador has `Input` class which represents single network input object. Under the hood, it wrapps Tensorflow's `placeholder` or Theano's equivalent (`TensorVariable`) class. When constructing complex network, one needs multiple of such objects. For example, `Optimizer`s require variables representing predicted values and correct values as its input. When defining network input `input_config` you can use either, single Input definition, list of definitions, or dictionary of definitions.\n\nThe following example defines the dictionary of Inputs, with keys `data` and `label`.\n\n```yaml\ninput_config:\n  data:\n    typename: Input\n    args:\n      name: input_image\n      shape: {image_shape}\n  label:\n    typename: Input\n    args:\n      name: label\n      shape: {label_size}\n      dtype: int64\n```\n\n\nThe following defines the list version of the previous example.\n\n\n```yaml\ninput_config:\n  - typename: Input\n    args:\n      name: input_image\n      shape: {image_shape}\n  - typename: Input\n    args:\n      name: label\n      shape: {label_size}\n      dtype: int64\n```\n\n\n#### Retrieving existing component\n\nLuchador uses retrieval mechanism similar to Tensorflow's `get_variable` but extends it to `Input` and `Tensor` (output) for flexible model construction. When constructing complex network, it is often required to retrieve Input, Output and Variable defined somewhere else. To retrieve existing instance, you can use the name of the instance.\n\n```yaml\ntypename: Input\nreuse: True\nname: input_image\n```\n\nretrieves `Input` instance named `input_image`. `reuse` attribute is requried to `Input` type.\n\n\n```yaml\ntypename: Tensor\nname: dense/output\n```\n\nretrieves `Tensor` instance which is output from layer named `dense`.\n\n\n```yaml\ntypename: Variable\nname: conv/filter\n```\n\nretrieves `Variable` instance which is filter parameter of `Conv2D` layer named `conv`.\n\n\n```yaml\ntypename: Model\nname: foo\nfetch: input\n```\n\nretrieves the `input` attribute of Model named `foo`.\n\n\n```yaml\ntypename: Model\nname: foo\nfetch: output\n```\n\nretrieves the `output` attribute of Model named `foo`.\n\n\n```yaml\ntypename: Model\nname: foo\nfetch: parameter\n```\n\nretrieves the list of trainable parameters of Model named `foo`.\n\n\n#### Graph Model\n\nIn Sequential model, the input to the model is passed through each layers, thus you do not need to specify the input to each layer. In contrast, in Graph model, each node (corresponds to layer in Sequential) has its own input. In the following example, Adam optimizer is constructed and the output from the Model named `error` is fed as `loss` and the parameters of Model named `classifier` is fed as `wrt`.\n\n```yaml\ntypename: Graph\nargs:\n  name: optimization\n  node_configs:\n    - typename: Adam\n      args:\n        name: Adam\n        learning_rate: 0.01\n      input:\n        loss:\n          typename: Model\n          name: error\n          fetch: output\n        wrt:\n          typename: Model\n          name: classifier\n          fetch: parameter\n```\n\n\n#### Container Model\n\nContainer model combines multiple models in dictionary manner. In the following example, a Container model which contains three models (`classifier`, `error` and `optimization`) is defined. (The contents of each model is omitted here, using YAML's alias feature.)\n\n```yaml\ntypename: Container\nargs:\n  model_configs:\n    - \u003c\u003c : *classifier\n      name: classifier\n    - \u003c\u003c : *error\n      name: error\n    - \u003c\u003c : *optimization\n      name: optimization\n```\n\n\nTo define input/output of Graph and Container model, one needs to add `input_config` manually.\n\n\n### Define new network component\n\nYou can add network component by subclassing the base class. For simplicity, here we forcus on Theano backend.\n\n#### 1. Layer\nTo add new layer, you need to subclass from `luchador.nn.BaseLayer`, then implement `build` method. `build` is called with the input Variable. Let's add [Parametric ReLU](https://en.wikipedia.org/wiki/Rectifier_%28neural_networks%29) Layer as an example.\n\n```python\nfrom luchador.nn import BaseLayer\n\n\nclass PReLU(BaseLayer):\n\tdef __init__(self, alpha):\n\t    super(PReLU, self).__init__(alpha=alpha)\n\n    def build(self, input_tensor):\n\t\talpha = self.args['alpha']\n        x = input_tensor.get()  # Unwrap the variable\n\t\toutput_tensor = T.switch(x \u003c 0, alpha * x, x)\n\t\treturn Tensor(output_tensor, shape=input_tensor.shape)\n```\n\nThen you can retrieve this with `luchador.nn.get_layer` function.\n\n```bash\n$ python\n\u003e\u003e\u003e import example.custom_layer\n2016-09-27 15:36:53,129:  INFO: Using theano backend\n\u003e\u003e\u003e from luchador.nn import get_layer\n\u003e\u003e\u003e get_layer('PReLU')\n\u003cclass 'example.custom_layer.PReLU'\u003e\n```\n\n## Example\n\nYou can run examples in example directory, such as MNIST classification, (Variational) AutoEncoder, GAN and DCGAN as follow. Use `--help` for how to run.\n\n```bash\npython example/classification/classify_mnist.py\npython example/autoencoder/train_vae.py\npython example/gan/train_dcgan.py\n```\n\nThe following is the network built using [DCGAN example](./example/gan/dcgan.yml).\n\u003cimg src=\"assets/gan_network.png\" width=\"512\"\u003e\n\n\n## Installation\n\n### Note on GPU backend\nLuchador has `luchador.nn.summary.SummaryWriter` class which wraps Tensorflow's SummaryWriter class so that not only `Tensorflow` backend but also `Thenao` backend can produce summary data which then can be visualized with `tensorboard`. However, when using `Theano` backend and if Tensorflow is installed with GPU enabled, Tensorflow detects that other library is using GPU and fail the program. Therefore it is strongly advised to setup a new python environment when you use Theano and Tensorflow (SummaryWriter) at the same time.\n\n\n### Dependencies\n\n- Luchador uses Thensorflow or Theano as neural network backend, so you need to install them. Refer to the installation instruction for each project.\n\nThe following dependencies are automatically installed during the installation.\n\n- `h5py` for saving neural network parameters\n- `ruamel.yaml` for parsing YAML files.\n\n\n### Installation\n\n1. Download the source code `git clone https://github.com/mthrok/luchador \u0026\u0026 cd luchador`\n3. Install `pip install .`\n\n\n### Update\n`pip install --upgrade --no-deps git+git://github.com/mthrok/luchador.git`\n\n\n### Setting backend\n\nAt the time of importing `luchador.nn` module, luchador checks environmental variable `LUCHADOR_NN_BACKEND` to detcide which backend it should use. Set value either `tensorflow` or `theano` to switch backend.\n\n```bash\nLUCHADOR_NN_BACKEND=theano luchador\n```\n\nWhen running Tensorflow backend, you can additionally configure default `dtype` and convolution data format  with `LUCHADOR_NN_DTYPE` and `LUCHADOR_NN_CONV_FORMAT`. These values are only effective in Tensorflow backend. To configure Theano, make `.theanorc` file in home directory and follow the instruction found at Theano documentation..\n\n```bash\nLUCHADOR_NN_BACKEND=tensorflow LUCHADOR_NN_CONV_FORMAT=NHWC LUCHADOR_NN_DTYPE=float32 luchador \n```\n\nOr programtically, you can set backend before importing `nn` module.\n\n```python\nimport luchador\nluchador.set_nn_backend('tensorflow')\nluchador.set_nn_conv_format('NHWC')\nluchador.set_nn_dtype('float32')\n\nimport luchador.nn  # tensorflow backend is loaded\n```\n\n\n## Development Plan\n\nSee [project list](https://github.com/mthrok/luchador/projects) for the list of plans.\n\n\n## Bug report\n\nAlthough automated integration test and unit test is set up via CircleCI, currently only small usage pattern is tested. If you find a bug, please open [an issue](https://github.com/mthrok/luchador/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmthrok%2Fluchador","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmthrok%2Fluchador","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmthrok%2Fluchador/lists"}