view release on metacpan or  search on metacpan

xgboost/dmlc-core/doc/parameter.md  view on Meta::CPAN

We also provide a more structured way to access the detail of the fields(name, default value, detailed description) via
```c++
std::vector<dmlc::ParamFieldInfo> fields = MyParam::__FIELDS__();
```

### Serialization of Parameters
One of the most common way to serialize the parameter is to convert it back to representation of ```std::map<string, string>```
by using the following code. 
```c++
std::map<string, string> dict = param.__DICT__();
```
The ```std::map<string, string>``` can further be serialized easily. This way of serialization is more device and platform(32/64 bit) agnostic.
However, this is not very compact, and recommended only used to serialize the general parameters set by the user.

Direct serialization and loading of JSON format is also support.

### Play with an Example
We provide an example program [parameter.cc](https://github.com/dmlc/dmlc-core/blob/master/example/parameter.cc), to 
demonstrate the usage mentioned above, and allow you to play with it and get sense of what is going on.

How does it work
----------------
Hope you like the parameter module so far. In this section, we will explain how does it work. Making such parameter module 
in ```C++``` is not easy. Because this basically means some way of reflection -- getting the information of fields in a 
structure out, which is not supported by ```C++```. 

Consider the following program, how do the Init function know the location of ```num_hidden```, and set it correctly
in ```Init``` function?

```c++
#include <vector>
#include <string>
#include <dmlc/parameter.h>

// declare the parameter, normally put it in header file.
struct MyParam : public dmlc::Parameter<MyParam> {
  float learning_rate;
  int num_hidden;
  // declare parameters
  DMLC_DECLARE_PARAMETER(MyParam) {
    DMLC_DECLARE_FIELD(num_hidden);
    DMLC_DECLARE_FIELD(learning_rate).set_default(0.01f);
  }
};

// register the parameter, this is normally in a cc file.
DMLC_REGISTER_PARAMETER(MyParam);

int main(int argc, char *argv[]) {
  MyParam param;
  std::vector<std::pair<std::string, std::string> > param_data = {
    {"num_hidden", "100"},
  };
  param.Init(param_data);
  return 0;
}
```

The secrete lies in the function ```DMLC_DECLARE_PARAMETER(MyParam)```, this is an macro defined in the parameter module.
If we expand the micro, the code roughly becomes the following code.

```c++
struct Parameter<MyParam> {
  template<typename ValueType>
  inline FieldEntry<ValueType>&
  DECLARE(ParamManagerSingleton<MyParam> *manager,
		  const std::string& key,
		  ValueType& ref){
	// offset gives a generic way to access the address of the field
	// from beginning of the structure.
	size_t offset = ((char*)&ref - (char*)this);
	parameter::FieldEntry<ValueType> *e =
        new parameter::FieldEntry<ValueType>(key, offset);
	manager->AddEntry(key, e);
	return *e;
  }
};

struct MyParam : public dmlc::Parameter<MyParam> {
  float learning_rate;
  int num_hidden;
  // declare parameters
  inline void __DECLARE__(ParamManagerSingleton<MyParam> *manager) {
    this->DECLARE(manager, "num_hidden", num_hidden);
	this->DECLARE(manager, "learning_rate", learning_rate).set_default(0.01f);
  }
};

// This code is only used to show the general idea.
// This code will only run once, the real code is done via singleton declaration pattern.
{
  static ParamManagerSingleton<MyParam> manager;
  MyParam tmp;
  tmp->__DECLARE__(&manager);
}
```
This is not the actual code that runs, but generally shows the idea on how it works. 
The key is that the structure layout is fixed for all the instances of objects.
To figure out how to access each of the field, we can
- Create an instance of MyParam, call the ```__DECLARE__``` function.
- The relative position of the field against the head of the structure is recorded into a global singleton.
- When we call ```Init```, we can get the ```offset``` from the singleton, and access the address of the field via ```(ValueType*)((char*)this + offset)```.

You are welcomed to check out the real details in [dmlc/parameter.h](https://github.com/dmlc/dmlc-core/blob/master/include/dmlc/parameter.h).
By using the generic template programming in C++, we have created a simple and useful parameter module for machine learning libraries.
This module is used extensively by DMLC projects. Hope you will find it useful as well :).