### Set up annealing schedule (beta vector) for iQSPR

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/7-inverse-design.html

Creates a beta vector for annealing, starting near 0 and increasing to 1 with an exponential-like schedule. The length of beta controls the number of iQSPR iterations; adding extra steps with beta=1 allows exploration of the posterior. The example prints the number of steps and the beta values.

```python
# set up annealing schedule in iQSPR
beta = np.hstack([np.linspace(0.01,0.2,20),np.linspace(0.21,0.4,10),np.linspace(0.4,1,10),np.linspace(1,1,10)])
print('Number of steps: %i' % len(beta))
print(beta)
```

```output
Number of steps: 50
[0.01       0.02       0.03       0.04       0.05       0.06
 0.07       0.08       0.09       0.1        0.11       0.12
 0.13       0.14       0.15       0.16       0.17       0.18
 0.19       0.2        0.21       0.23111111 0.25222222 0.27333333
 0.29444444 0.31555556 0.33666667 0.35777778 0.37888889 0.4
 0.4        0.46666667 0.53333333 0.6        0.66666667 0.73333333
 0.8        0.86666667 0.93333333 1.         1.         1.
 1.         1.         1.         1.         1.         1.
 1.         1.        ]
```

--------------------------------

### GET /methods

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/mdl/mdl.html

Lists all methods available in the system.

```APIDOC
## GET /methods

### Description
Lists all methods.

### Method
GET

### Endpoint
/methods

### Response
#### Success Response (200)
- **query** (Querying object) - Querying object for further operations.

#### Response Example
```json
{
  "data": []
}
```
```

--------------------------------

### SGD optimizer usage example

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.model.training.html

Shows the typical usage pattern for the SGD optimizer: instantiate it with learning rate and momentum, attach model parameters, zero gradients, compute loss and backpropagate, then step. The trailing comma in the last line is part of the original example.

```python
>>> optimizer = torch.optim.SGD(lr=0.1, momentum=0.9)
>>> optimizer(model.parameters())
>>> optimizer.zero_grad()
>>> loss_fn(model(input), target).backward()
>>> optimizer.step(),
```

--------------------------------

### setup.py: PackageInfo class and main setup block

Source: https://xenonpy.readthedocs.io/en/latest/_modules/setup.html

Full setup.py source for the xenonpy package. Defines PackageInfo to load metadata from conf.yml and a main block that builds setup parameters, including package discovery, version, URLs, license, platforms, and classifiers. The code is executed when the script is run directly.

```python
#  Copyright (c) 2021. yoshida-lab. All rights reserved.
#  Use of this source code is governed by a BSD-style
#  license that can be found in the LICENSE file.

# -*- coding: utf-8 -*-

# uncomment this for compatibility with py27
# from __future__ import print_function

import os
from pathlib import Path

from ruamel.yaml import YAML
from setuptools import setup, find_packages

# YOUR PACKAGE NAME
__package__ = 'xenonpy'



[docs]class PackageInfo(object):
    """
    Appendix
    --------
    classifiers: https://pypi.python.org/pypi?%3Aaction=list_classifiers
    """

    def __init__(self, conf_file):
        yaml = YAML(typ='safe')
        yaml.indent(mapping=2, sequence=4, offset=2)
        with open(conf_file, 'r') as f:
            self._info = yaml.load(f)
        self.name = __package__


[docs]    @staticmethod
    def requirements(filename="requirements.txt"):
        """
        Return requirements list from a text file.

        Parameters
        ----------
        filename: str
            Name of requirement file.

        Returns
        -------
            str-list
        """
        try:
            require = list()
            f = open(filename, "rb")
            for line in f.read().decode("utf-8").split("\n"):
                line = line.strip()
                if "#" in line:
                    line = line[:line.find("#")].strip()
                if line:
                    require.append(line)
        except IOError:
            print("'{}' not found!".format(filename))
            require = list()

        return require


    def __getattr__(self, item: str):
        try:
            return self._info[item]
        except KeyError:
            return None



if __name__ == "__main__":
    # --- Automatically generate setup parameters ---
    cwd = Path(__file__).parent / __package__ / 'conf.yml'
    package = PackageInfo(str(cwd))

    # Your package name
    PKG_NAME = package.name

    # Your GitHub user name
    GITHUB_USERNAME = package.github_username

    # Short description will be the description on PyPI
    SHORT_DESCRIPTION = package.short_description  # GitHub Short Description

    # Long description will be the body of content on PyPI page
    LONG_DESCRIPTION = package.long_description

    # Version number, VERY IMPORTANT!
    VERSION = package.version + package.release

    # Author and Maintainer
    AUTHOR = package.author

    # Author email
    AUTHOR_EMAIL = package.author_email

    MAINTAINER = package.maintainer

    MAINTAINER_EMAIL = package.maintainer_email

    PACKAGES, INCLUDE_PACKAGE_DATA, PACKAGE_DATA, PY_MODULES = (
        None,
        None,
        None,
        None,
    )

    # It's a directory style package
    if os.path.exists(__file__[:-8] + PKG_NAME):
        # Include all sub packages in package directory
        PACKAGES = find_packages(exclude=["*.tests", "*.tests.*", "tests.*", "tests"])

        # Include everything in package directory
        INCLUDE_PACKAGE_DATA = True
        PACKAGE_DATA = {
            "": ["*.*"],
        }

    # It's a single script style package
    elif os.path.exists(__file__[:-8] + PKG_NAME + ".py"):
        PY_MODULES = [
            PKG_NAME,
        ]

    # Project Url
    GITHUB_URL = "https://github.com/{0}/{1}".format(GITHUB_USERNAME, PKG_NAME)
    # Use todays date as GitHub release tag
    RELEASE_TAG = 'v' + VERSION
    # Source code download url
    DOWNLOAD_URL = "https://github.com/{0}/{1}/archive/{2}.tar.gz".format(GITHUB_USERNAME, PKG_NAME, RELEASE_TAG)

    LICENSE = package.license or "'__license__' not found in '%s.__init__.py'!" % PKG_NAME

    PLATFORMS = [
        "Windows",
        "MacOS",
        "Unix",
    ]

    CLASSIFIERS = [
        "Development Status :: 4 - Beta",
        "Intended Audience :: Science/Research",
        "License :: OSI Approved :: BSD License",
        "Natural Language :: English",
        "Operating System :: Microsoft :: Windows",
        "Operating System :: MacOS",
        "Operating System :: Unix",
        "Programming Language :: Python :: 3.7",
        "Programming Language :: Python :: 3.8",
        "Programming Language :: Python :: 3.9",
    ]
```

--------------------------------

### KLDivLoss usage examples with batchmean reduction

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Two usage examples for nn.KLDivLoss. The first shows the default log_target=False case, and the second shows log_target=True. Both use reduction='batchmean' and demonstrate how to prepare input and target tensors.

```python
>>> import torch.nn.functional as F
>>> kl_loss = nn.KLDivLoss(reduction="batchmean")
>>> # input should be a distribution in the log space
>>> input = F.log_softmax(torch.randn(3, 5, requires_grad=True), dim=1)
>>> # Sample a batch of distributions. Usually this would come from the dataset
>>> target = F.softmax(torch.rand(3, 5), dim=1)
>>> output = kl_loss(input, target)
```

```python
>>> kl_loss = nn.KLDivLoss(reduction="batchmean", log_target=True)
>>> log_target = F.log_softmax(torch.rand(3, 5), dim=1)
>>> output = kl_loss(input, log_target)
```

--------------------------------

### Example: MyLogLikelihood subclass of BaseLogLikelihoodSet

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/inverse/base.html

Example of using BaseLogLikelihoodSet to organize log-likelihoods.

```python
class MyLogLikelihood(BaseLogLikelihoodSet):
    def __init__(self):
        super().__init__()

        self.loglike1 = SomeFeature1()
        self.loglike1 = SomeFeature2()
        self.loglike2 = SomeFeature3()
        self.loglike2 = SomeFeature4()
```

--------------------------------

### MSELoss usage example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Shows how to instantiate and use nn.MSELoss with a random input and target, then call backward(). The input requires gradients.

```python
>>> loss = nn.MSELoss()
>>> input = torch.randn(3, 5, requires_grad=True)
>>> target = torch.randn(3, 5)
>>> output = loss(input, target)
>>> output.backward()
```

--------------------------------

### L1Loss usage example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Example from the L1Loss docstring showing how to instantiate the loss, create random input and target tensors, compute the loss, and call backward.

```python
>>> loss = nn.L1Loss()
>>> input = torch.randn(3, 5, requires_grad=True)
>>> target = torch.randn(3, 5)
>>> output = loss(input, target)
>>> output.backward()
```

--------------------------------

### SGD optimizer class initialization with example usage

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/model/training/optimizer.html

Defines the SGD optimizer class that wraps PyTorch's optim.SGD. The __init__ method accepts learning rate, momentum, dampening, weight decay, and nesterov flag. The docstring includes an example usage showing how to instantiate and use the optimizer.

```python
class SGD(BaseOptimizer):

    def __init__(self, *, lr=0.01, momentum=0, dampening=0, weight_decay=0, nesterov=False):
        r"""Implements stochastic gradient descent (optionally with momentum).

        Nesterov momentum is based on the formula from
        `On the importance of initialization and momentum in deep learning`__.

        Args:
            lr (float): learning rate
            momentum (float, optional): momentum factor (default: 0)
            weight_decay (float, optional): weight decay (L2 penalty) (default: 0)
            dampening (float, optional): dampening for momentum (default: 0)
            nesterov (bool, optional): enables Nesterov momentum (default: False)

        Example:
            >>> optimizer = torch.optim.SGD(lr=0.1, momentum=0.9)
            >>> optimizer(model.parameters())
            >>> optimizer.zero_grad()
            >>> loss_fn(model(input), target).backward()
            >>> optimizer.step(),

        __ http://www.cs.toronto.edu/%7Ehinton/absps/momentum.pdf

        .. note::
            The implementation of SGD with Momentum/Nesterov subtly differs from
            Sutskever et. al. and implementations in some other frameworks.

            Considering the specific case of Momentum, the update can be written as

            .. math::
                      v = \rho * v + g \\
                      p = p - lr * v

            where p, g, v and :math:`\rho` denote the parameters, gradient,
            velocity, and momentum respectively.

            This is in contrast to Sutskever et. al. and
            other frameworks which employ an update of the form

            .. math::
                 v = \rho * v + lr * g \\
                 p = p - v

            The Nesterov version is analogously modified.
        """

        super().__init__(optim.SGD,
                         lr=lr,
                         momentum=momentum,
                         dampening=dampening,
                         weight_decay=weight_decay,
                         nesterov=nesterov)
```

--------------------------------

### Import XenonPy and check version

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/7-inverse-design.html

Initial setup step to import the xenonpy package and display its version. The output shows version '0.6.2'.

```python
import xenonpy
xenonpy.__version__
```

--------------------------------

### Create and sync Conda environment

Source: https://xenonpy.readthedocs.io/en/latest/installation.html

Creates a fresh Conda environment and syncs it with a preset environment file, installing the required dependencies.

```bash
$ conda create -n <env_name_you_liked> python={3.6 or 3.7}  # use `conda create` command to create a fresh environment with specific name and python version
$ conda env update -n <env_name_you_created> -f <path_to_env_file>  # use `conda env update` command to sync packages with the preset environment
```

--------------------------------

### Basic BCEWithLogitsLoss example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Demonstrates the basic usage of BCEWithLogitsLoss with random input and target tensors, followed by a backward pass.

```python
>>> loss = nn.BCEWithLogitsLoss()
>>> input = torch.randn(3, requires_grad=True)
>>> target = torch.empty(3).random_(2)
>>> output = loss(input, target)
>>> output.backward()
```

--------------------------------

### KLDivLoss usage example

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.model.training.html

Demonstrates how to use nn.KLDivLoss with reduction='batchmean' and optionally log_target=True. The input should be in log-space, and the target can be in log-space if log_target is True.

```python
>>> import torch.nn.functional as F
>>> kl_loss = nn.KLDivLoss(reduction="batchmean")
>>> # input should be a distribution in the log space
>>> input = F.log_softmax(torch.randn(3, 5, requires_grad=True), dim=1)
>>> # Sample a batch of distributions. Usually this would come from the dataset
>>> target = F.softmax(torch.rand(3, 5), dim=1)
>>> output = kl_loss(input, target)

>>> kl_loss = nn.KLDivLoss(reduction="batchmean", log_target=True)
>>> log_target = F.log_softmax(torch.rand(3, 5), dim=1)
>>> output = kl_loss(input, log_target)
```

--------------------------------

### Clone XenonPy repository for development

Source: https://xenonpy.readthedocs.io/en/latest/installation.html

Clone the XenonPy repository from GitHub, the first step to install in development mode.

```bash
$ git clone https://github.com/yoshida-lab/XenonPy.git
```

--------------------------------

### Create and update 'xenonpy' environment with cuda101.yml

Source: https://xenonpy.readthedocs.io/en/latest/installation.html

Creates a Python 3.7 environment named 'xenonpy' and then updates it with the cuda101.yml file, installing all listed packages.

```bash
$ conda create -n xenonpy python=3.7
$ conda env update -n xenonpy -f cuda101.yml
```

--------------------------------

### Build sample data with preset.build

Source: https://xenonpy.readthedocs.io/en/latest/tutorial.html

Builds sample data for the tutorials using the Materials Project API. Requires an API key from the Materials Project. The data is saved to ~/.xenonpy/userdata.

```python
>>> from xenonpy.datatools import preset
>>> preset.build('mp_samples', api_key='your api key')

```

--------------------------------

### Install XenonPy development environment

Source: https://xenonpy.readthedocs.io/en/latest/installation.html

Install XenonPy in development mode: update your conda environment with the extra development tools and install the package in editable mode.

```bash
$ cd XenonPy
$ conda env update -n <your_env_name> -f devtools/extra_env.yml
$ pip install -e .
```

--------------------------------

### Run tools notebook

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/6-transfer_learning.html

Loads common packages and in-house functions used in the tutorial by running the 'tools.ipynb' notebook.

```python
%run tools.ipynb
```

--------------------------------

### TripletMarginWithDistanceLoss usage examples

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

These examples show how to use the TripletMarginWithDistanceLoss with built-in, custom, and lambda distance functions. The first example uses nn.PairwiseDistance, the second defines a custom l_infinity function, and the third uses a lambda with F.cosine_similarity. Each example initializes embeddings, computes the loss, and calls backward().

```python
>>> # Initialize embeddings
>>> embedding = nn.Embedding(1000, 128)
>>> anchor_ids = torch.randint(0, 1000, (1,))
>>> positive_ids = torch.randint(0, 1000, (1,))
>>> negative_ids = torch.randint(0, 1000, (1,))
>>> anchor = embedding(anchor_ids)
>>> positive = embedding(positive_ids)
>>> negative = embedding(negative_ids)
>>>
>>> # Built-in Distance Function
>>> triplet_loss = \
>>>     nn.TripletMarginWithDistanceLoss(distance_function=nn.PairwiseDistance())
>>> output = triplet_loss(anchor, positive, negative)
>>> output.backward()
>>>
>>> # Custom Distance Function
>>> def l_infinity(x1, x2):
>>>     return torch.max(torch.abs(x1 - x2), dim=1).values
>>>
>>> # xdoctest: +SKIP("FIXME: Would call backwards a second time")
>>> triplet_loss = (
>>>     nn.TripletMarginWithDistanceLoss(distance_function=l_infinity, margin=1.5))
>>> output = triplet_loss(anchor, positive, negative)
>>> output.backward()
>>>
>>> # Custom Distance Function (Lambda)
>>> triplet_loss = (
>>>     nn.TripletMarginWithDistanceLoss(
>>>         distance_function=lambda x, y: 1.0 - F.cosine_similarity(x, y)))
>>> output = triplet_loss(anchor, positive, negative)
>>> output.backward()
```

--------------------------------

### Initialize Compositions calculator

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/2-descriptor.html

Creates a Compositions instance and prints its structure, showing the composition featurizer group with its sub-featurizers.

```python
>>> from xenonpy.descriptor import Compositions
>>> cal = Compositions()
>>> cal
Compositions:
  |- composition:
  |  |- Counting
  |  |- WeightedAverage
  |  |- WeightedSum
  |  |- WeightedVariance
  |  |- GeometricMean
  |  |- HarmonicMean
  |  |- MaxPooling
  |  |- MinPooling

```

--------------------------------

### Update XenonPy with pip install -U

Source: https://xenonpy.readthedocs.io/en/latest/installation.html

Update an existing XenonPy installation to the latest version.

```bash
$ pip install -U xenonpy
```

--------------------------------

### PoissonNLLLoss usage example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Shows how to use nn.PoissonNLLLoss with random input and target tensors. The example includes a backward pass.

```python
>>> loss = nn.PoissonNLLLoss()
>>> log_input = torch.randn(5, 2, requires_grad=True)
>>> target = torch.randn(5, 2)
>>> output = loss(log_input, target)
>>> output.backward()
```

--------------------------------

### Example MyDescriptor subclass

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/descriptor/base.html

Example of a custom descriptor class that inherits from BaseDescriptor. It initializes four features with n_jobs parameter.

```python
class MyDescriptor(BaseDescriptor):

    def __init__(self, n_jobs=-1):
        self.descriptor = SomeFeature1(n_jobs)
        self.descriptor = SomeFeature2(n_jobs)
        self.descriptor = SomeFeature3(n_jobs)
        self.descriptor = SomeFeature4(n_jobs)
```

--------------------------------

### xenonpy.model.nn.wrap.Init

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.model.nn.html

Wrapper class providing static methods for initialization, currently includes uniform initialization.

```APIDOC
## Init

### Description
Wrapper class for initialization methods.

### Static Methods
#### uniform(*, scale=0.1)
Uniform initialization.
```

--------------------------------

### BCELoss usage example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Example of using BCELoss with a Sigmoid layer. The input is a random tensor with requires_grad=True, and the target is a random binary tensor. The loss is computed and backpropagated.

```python
>>> m = nn.Sigmoid()
>>> loss = nn.BCELoss()
>>> input = torch.randn(3, requires_grad=True)
>>> target = torch.empty(3).random_(2)
>>> output = loss(m(input), target)
>>> output.backward()
```

--------------------------------

### TopologicalTorsion.__init__

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/descriptor/fingerprint.html

Initializes the TopologicalTorsion featurizer with parameters for parallel processing, bit length, counting mode, input type, and error handling.

```APIDOC
## TopologicalTorsion.__init__

### Description
Initializes the TopologicalTorsion featurizer with configurable parameters for parallel processing, bit length, counting mode, input type, and error handling.

### Method
Constructor

### Parameters
- **n_jobs** (int) - Optional - The number of jobs to run in parallel for both fit and predict. Can be -1 or # of cups. Set -1 to use all cpu cores (default).
- **n_bits** (int) - Required - Fixed bit length based on folding.
- **bit_per_entry** (int) - Optional - Number of bits used to represent a single entry (only for non-counting case). Default value follows rdkit default.
- **counting** (boolean) - Required - Record counts of the entries instead of bits only.
- **input_type** (string) - Required - Set the specific type of transform input. Set to ``mol`` (default) to ``rdkit.Chem.rdchem.Mol`` objects as input. When set to ``smlies``, ``transform`` method can use a SMILES list as input. Set to ``any`` to use both. If input is SMILES, ``Chem.MolFromSmiles`` function will be used inside. for ``None`` returns, a ``ValueError`` exception will be raised.
- **on_errors** (string) - Optional - How to handle exceptions in feature calculations. Can be 'nan', 'keep', 'raise'. When 'nan', return a column with ``np.nan``. The length of column corresponding to the number of feature labs. When 'keep', return a column with exception objects. The default is 'raise' which will raise up the exception.
- **target_col** - Optional - Only relevant when input is pd.DataFrame, otherwise ignored. Specify a single column to be used for transformation. If ``None``, all columns of the pd.DataFrame is used. Default is None.

### Notes
- The constructor calls the parent class initializer with n_jobs, on_errors, return_type, and target_col.
- Sets self.input_type, self.n_bits, self.bit_per_entry (default 4 if None), self.counting, and self.__authors__.
```

--------------------------------

### SparseAdam

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/model/training/optimizer.html

Implements the lazy version of the Adam algorithm suitable for sparse tensors. Only moments that show up in the gradient get updated, and only those portions of the gradient get applied to the parameters.

```APIDOC
## SparseAdam

### Description
Implements lazy version of Adam algorithm suitable for sparse tensors. In this variant, only moments that show up in the gradient get updated, and only those portions of the gradient get applied to the parameters.

### Constructor
`SparseAdam(*, lr=0.001, betas=(0.9, 0.999), eps=1e-08)`

### Parameters
- **lr** (float, optional) - Learning rate (default: 1e-3)
- **betas** (Tuple[float, float], optional) - Coefficients used for computing running averages of gradient and its square (default: (0.9, 0.999))
- **eps** (float, optional) - Term added to the denominator to improve numerical stability (default: 1e-8)

### References
- [Adam: A Method for Stochastic Optimization](https://arxiv.org/abs/1412.6980)
```

--------------------------------

### Trainer output after initialization

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/4-random_nn_model_and_training.html

Shows the Trainer's configuration after creation, including the model architecture and optimizer parameters.

```python
[19]:
```

```python
Trainer(clip_grad=None, cuda=None, epochs=200, loss_func=MSELoss(),
        lr_scheduler=None,
        model=SequentialLinear(
  (layer_0): LinearLayer(
    (linear): Linear(in_features=290, out_features=232, bias=True)
    (dropout): Dropout(p=0.1)
    (normalizer): BatchNorm1d(232, eps=0.1, momentum=0.1, affine=True, track_running_stats=True)
    (activation): ReLU()
  )
  (layer_1): LinearLayer(
    (linear): Li...
    (linear): Linear(in_features=116, out_features=58, bias=True)
    (dropout): Dropout(p=0.1)
    (normalizer): BatchNorm1d(58, eps=0.1, momentum=0.1, affine=True, track_running_stats=True)
    (activation): ReLU()
  )
  (output): Linear(in_features=58, out_features=1, bias=True)
),
        non_blocking=False,
        optimizer=Adam (
Parameter Group 0
    amsgrad: False
    betas: (0.9, 0.999)
    eps: 1e-08
    lr: 0.01
    weight_decay: 0
))
```

--------------------------------

### TripletMarginLoss usage example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Shows how to instantiate and use nn.TripletMarginLoss with random tensors. The example creates anchor, positive, and negative tensors with requires_grad=True, computes the loss, and calls backward().

```python
>>> triplet_loss = nn.TripletMarginLoss(margin=1.0, p=2)
>>> anchor = torch.randn(100, 128, requires_grad=True)
>>> positive = torch.randn(100, 128, requires_grad=True)
>>> negative = torch.randn(100, 128, requires_grad=True)
>>> output = triplet_loss(anchor, positive, negative)
>>> output.backward()
```

--------------------------------

### Handle mp_samples key in sync method

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/datatools/preset.html

Processes the 'mp_samples' key: requires an API key, loads material IDs from kwargs or a default file, builds the dataset, saves to a pickle file, and creates an index. Raises errors for missing API key or invalid mp_ids.

```python
for key in keys:
    if key is 'mp_samples':
        if 'api_key' not in kwargs:
            raise RuntimeError('api key of materials projects database is needed')
        if 'mp_ids' in kwargs:
            ids = kwargs['mp_ids']
            if isinstance(ids, (list, tuple)):
                mp_ids = ids
            elif isinstance(ids, str):
                mp_ids = [s.decode('utf-8') for s in np.loadtxt(ids, 'S20')]
            else:
                raise ValueError(
                    'parameter `mp_ids` can only be a str to specific the ids file path'
                    'or a list-like object contain the ids')
        else:
            ids = Path(__file__).absolute().parent / 'mp_ids.txt'
            mp_ids = [s.decode('utf-8') for s in np.loadtxt(str(ids), 'S20')]
        data = mp_builder(kwargs['api_key'], mp_ids)
        if not save_to:
            save_to = Path(config('userdata')) / 'mp_samples.pd.xz'
            save_to = save_to.expanduser().absolute()
        data.to_pickle(save_to)
        self._make_index(prefix=['dataset'])
        return

raise ValueError('no available key(s) in %s, these can only be %s' % (keys, self.__builder__))
```

--------------------------------

### Initialize MDL client

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/6-transfer_learning.html

Creates an MDL instance to access XenonPy's model database. The output shows the default API key and endpoint.

```python
from xenonpy.mdl import MDL

mdl = MDL()
mdl

mdl.version
```

```text
MDL(api_key='anonymous.user.key', endpoint='http://xenon.ism.ac.jp/api')
```

```text
'0.1.1'
```

--------------------------------

### BCEWithLogitsLoss with pos_weight example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Shows how to use BCEWithLogitsLoss with a pos_weight tensor to weight positive examples. The output is a tensor with value approximately 0.20, representing -log(sigmoid(1.5)).

```python
>>> target = torch.ones([10, 64], dtype=torch.float32)  # 64 classes, batch size = 10
>>> output = torch.full([10, 64], 1.5)  # A prediction (logit)
>>> pos_weight = torch.ones([64])  # All weights are equal to 1
>>> criterion = torch.nn.BCEWithLogitsLoss(pos_weight=pos_weight)
>>> criterion(output, target)  # -log(sigmoid(1.5))
tensor(0.20...)
```

--------------------------------

### MarginRankingLoss usage example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Shows how to instantiate and use MarginRankingLoss with random inputs and a target tensor. The example creates a loss object, generates input tensors with requires_grad=True, computes the loss, and calls backward().

```python
>>> loss = nn.MarginRankingLoss()
>>> input1 = torch.randn(3, requires_grad=True)
>>> input2 = torch.randn(3, requires_grad=True)
>>> target = torch.randn(3).sign()
>>> output = loss(input1, input2, target)
>>> output.backward()
```

--------------------------------

### get_checkpoint()

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.model.training.html

Get a checkpoint from the trainer.

```APIDOC
## get_checkpoint(checkpoint=None)

### Description
Gets a checkpoint from the trainer based on the given identifier.

### Parameters
- **checkpoint** - Optional - Checkpoint identifier.

### Returns
Checkpoint object.

```

--------------------------------

### Create Trainer with Adam optimizer and MSELoss

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/4-random_nn_model_and_training.html

Initializes a Trainer with a model, Adam optimizer (lr=0.01), and MSELoss. The trainer is displayed to show its configuration.

```python
trainer = Trainer(
    model=model,
    optimizer=Adam(lr=0.01),
    loss_func=MSELoss()
)
trainer
```

--------------------------------

### Instantiate Structures calculator and inspect default featurizers

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/2-descriptor.html

Import the Structures descriptor calculator from xenonpy.descriptor, create an instance, and display it to see the default featurizer group 'structure' containing RadialDistributionFunction and OrbitalFieldMatrix.

```python
>>> from xenonpy.descriptor import Structures
>>> cal = Structures()
>>> cal
Structures:
  |- structure:
  |  |- RadialDistributionFunction
  |  |- OrbitalFieldMatrix

```

--------------------------------

### MDL.get_method_detail

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.mdl.html

Get method detail by name.

```APIDOC
## MDL.get_method_detail

### Description
Get method detail by name.

### Method
get_method_detail

### Signature
`get_method_detail(name)`

### Parameters
- **name** (`str`) - Required - 

### Returns
- **query** - Querying object.
```

--------------------------------

### MDL.get_descriptor_detail

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.mdl.html

Get descriptor detail by name.

```APIDOC
## MDL.get_descriptor_detail

### Description
Get descriptor detail by name.

### Method
get_descriptor_detail

### Signature
`get_descriptor_detail(name)`

### Parameters
- **name** (`str`) - Required - 

### Returns
- **query** - Querying object.
```

--------------------------------

### NLLLoss.__init__

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Initializes the NLLLoss module with optional weight, size_average, ignore_index, reduce, and reduction parameters.

```APIDOC
## NLLLoss.__init__

### Description
Constructor for the NLLLoss class.

### Method
__init__

### Signature
__init__(self, weight: Optional[Tensor] = None, size_average=None, ignore_index: int = -100, reduce=None, reduction: str = 'mean') -> None

### Parameters
- **weight** (Optional[Tensor]) - Optional - A manual rescaling weight given to each class.
- **size_average** (bool, optional) - Optional - Deprecated, see reduction.
- **ignore_index** (int) - Optional - Specifies a target value that is ignored and does not contribute to the input gradient. Default: -100
- **reduce** (bool, optional) - Optional - Deprecated, see reduction.
- **reduction** (str) - Optional - Specifies the reduction to apply: 'none' | 'mean' | 'sum'. Default: 'mean'

### Returns
None
```

--------------------------------

### NLLLoss usage example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Shows how to use nn.NLLLoss with a LogSoftmax layer for a 1D input of size N x C. The target tensor must have values in the range 0 <= value < C. The example includes a backward pass.

```python
>>> m = nn.LogSoftmax(dim=1)
>>> loss = nn.NLLLoss()
>>> # input is of size N x C = 3 x 5
>>> input = torch.randn(3, 5, requires_grad=True)
>>> # each element in target has to have 0 <= value < C
>>> target = torch.tensor([1, 0, 4])
>>> output = loss(m(input), target)
>>> output.backward()
```

--------------------------------

### MDL.get_model_urls

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.mdl.html

Get download url by model id.

```APIDOC
## MDL.get_model_urls

### Description
Get download url by model id.

### Method
get_model_urls

### Signature
`get_model_urls(*model_ids)`

### Parameters
- **model_ids** (`int`) - Required - Model id.

### Returns
- **query** - Querying object.
```

--------------------------------

### MDL.get_model_detail

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.mdl.html

Get model detail by model id.

```APIDOC
## MDL.get_model_detail

### Description
Get model detail by model id.

### Method
get_model_detail

### Signature
`get_model_detail(model_id)`

### Parameters
- **model_id** (`int`) - Required - Model id.

### Returns
- **query** - Querying object.
```

--------------------------------

### Set up initial molecules for iQSPR

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/7-inverse-design.html

Selects 25 initial molecules from the dataset with HOMO-LUMO gap > 4 eV, using a fixed random seed for reproducibility. The number of initial molecules determines the number generated per iteration; at least 100-1000 is recommended to avoid local trapping.

```python
# set up initial molecules for iQSPR
np.random.seed(201906) # fix the random seed
cans = [Chem.MolToSmiles(Chem.MolFromSmiles(smi)) for i, smi in enumerate(data_ss['SMILES'])
       if (data_ss['HOMO-LUMO gap'].iloc[i] > 4)]
init_samples = np.random.choice(cans, 25)
print(init_samples)
```

```output
['CC(Cc1ccccc1)NCCn1cnc2c1c(=O)n(C)c(=O)n2C' 'CN1CCN(C)C1=O' 'N#CO'
 'COC1C(O)C(N)C(OC2OC(C(C)N)CCC2N)C(O)C1N(C)C(=O)CN' 'CCCCOP(N)(=O)OCCCC'
 'NS(=O)(=O)Cl' 'CCSC(=O)N(CC)CC' 'CCCCCC=CCC=CCC=CCCCCC(=O)O'
 'CCCCCC=CCC=CCC=CC=CC(O)CCCC(=O)O'
 'CC1NCCc2c(C(=O)N3CCCCC3)[nH]c3cccc1c23' 'ClC1C=CC(Cl)C(Cl)C1Cl'
 'CC1=CC(=O)CC1' 'CC1C(=O)NC(=O)N(C2CCCCC2)C1=O'
 'O=[N+]([O-])c1cc2nc(C(F)(F)F)[nH]c2cc1Cl' 'O=C1C=C2NC(C(=O)O)C=C2CC1=O'
 'CCSC(=O)N(CC)CC' 'CCCCCCCCOc1ccc(C(=O)c2ccccc2O)c(O)c1'
 'COc1ccc2c(c1)CCC(c1ccccc1)C2(O)c1ccccn1'
 'CCN(CCOC(=O)C(OC)(c1ccccc1)c1ccccc1)CC(C)C' 'COc1ccccc1NC(=O)CC(C)=O'
 'CC1CC2C(=CC1=O)CCC1C2CCC2(C)C1CCC2(C)O' 'C1COCCN1' 'NCCNCCO'
 'CCC(C)Cc1cccc(O)c1C' 'COC(F)(F)CCl'
```

```output
RDKit WARNING: [23:16:50] WARNING: not removing hydrogen atom without neighbors
```

--------------------------------

### GET /descriptors

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/mdl/mdl.html

Lists all descriptors available in the system.

```APIDOC
## GET /descriptors

### Description
Lists all descriptors.

### Method
GET

### Endpoint
/descriptors

### Response
#### Success Response (200)
- **query** (Querying object) - Querying object for further operations.

#### Response Example
```json
{
  "data": []
}
```
```

--------------------------------

### Use a BaseFeaturizer in a scikit-learn style

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.descriptor.html

Shows how to instantiate a featurizer and call fit_transform on input data X, following the scikit-learn API.

```python
featurizer = SomeFeaturizer()
features = featurizer.fit_transform(X)

```

--------------------------------

### Timer.start

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.utils.html

Start the timer for a given function name.

```APIDOC
## Timer.start

### Description
Start the timer for a given function name.

### Method
start

### Signature
start(fn_name='main')

### Parameters
- **fn_name** (str) - Optional - Name of the function to time. Defaults to 'main'.

### Returns
None
```

--------------------------------

### CrossEntropyLoss usage examples with class indices and class probabilities

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Two usage examples for nn.CrossEntropyLoss: one with target class indices and one with target class probabilities. Both create random input and target tensors, compute the loss, and call backward().

```python
>>> # Example of target with class indices
>>> loss = nn.CrossEntropyLoss()
>>> input = torch.randn(3, 5, requires_grad=True)
>>> target = torch.empty(3, dtype=torch.long).random_(5)
>>> output = loss(input, target)
>>> output.backward()
>>>
>>> # Example of target with class probabilities
>>> input = torch.randn(3, 5, requires_grad=True)
>>> target = torch.randn(3, 5).softmax(dim=1)
>>> output = loss(input, target)
>>> output.backward()
```

--------------------------------

### Training workflow with Persist extension

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/4-random_nn_model_and_training.html

Creates a SequentialLinear model, generates a model name, sets up Persist with required path and optional metadata, extends the trainer, resets the model, fits the training data, and finally calls persist with splitter and data indices after training.

```python
model = SequentialLinear(290, 1, h_neurons=(0.8, 0.6, 0.4, 0.2))
model

model_name = make_name(model)
persist = Persist(
    f'trained_models/{model_name}',
    # -^- required -^-

    # -v- optional -v-
    increment=False,
    sync_training_step=True,
    author='Chang Liu',
    email='liu.chang.1865@gmail.com',
    dataset='materials project',
)
_ = trainer.extend(persist)
trainer.reset(to=model)

trainer.fit(training_dataset=train_dataset, validation_dataset=val_dataset, epochs=400)
persist(splitter=sp, data_indices=prop.index.tolist())  # <-- calling of this method only after the model training

```

--------------------------------

### Load sample data from Materials Project

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/5-pre-trained_model_library.html

Loads the 'mp_samples' preset dataset from the Materials Project. Requires a Materials Project API key if the data is not already cached.

```python
# if you have not had the samples data
# preset.build('mp_samples', api_key=<your materials project api key>)
from xenonpy.datatools import preset

data = preset.mp_samples
data.head(3)

```

--------------------------------

### MDL.get_model_details

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.mdl.html

Get multiply model detail by their ids in one querying.

```APIDOC
## MDL.get_model_details

### Description
Get multiply model detail by their ids in one querying.

### Method
get_model_details

### Signature
`get_model_details(model_ids)`

### Parameters
- **model_ids** (`List[int]`) - Required - Model id.

### Returns
- **query** - Querying object.
```

--------------------------------

### GaussianLogLikelihood.__init__

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/inverse/iqspr/estimator.html

Initializes a GaussianLogLikelihood instance with a descriptor calculator and optional estimators and target bounds.

```APIDOC
## GaussianLogLikelihood.__init__

### Description
Initializes a GaussianLogLikelihood instance with a descriptor calculator and optional estimators and target bounds.

### Method
Constructor

### Signature
`GaussianLogLikelihood(descriptor: Union[BaseFeaturizer, BaseDescriptor], *, targets={}, **estimators: BaseEstimator)`

### Parameters
- **descriptor** (BaseFeaturizer or BaseDescriptor) - Required - Descriptor calculator.
- **estimators** (BaseEstimator) - Optional - Gaussian estimators following the scikit-learn style. Must provide a `predict` method that returns `(mean, std)`. Defaults to BayesianRidge.
- **targets** (dictionary) - Optional - Upper and lower bounds for each property to calculate the Gaussian CDF probability.

### Raises
- **TypeError** - If descriptor is not a subclass of BaseFeaturizer or BaseDescriptor.

```

--------------------------------

### GET /methods/{name}

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/mdl/mdl.html

Retrieves detailed information about a specific method.

```APIDOC
## GET /methods/{name}

### Description
Gets method detail by name.

### Method
GET

### Endpoint
/methods/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the method.

### Response
#### Success Response (200)
- **query** (Querying object) - Querying object for further operations.

#### Response Example
```json
{
  "data": {}
}
```
```

--------------------------------

### GET /descriptors/{name}

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/mdl/mdl.html

Retrieves detailed information about a specific descriptor.

```APIDOC
## GET /descriptors/{name}

### Description
Gets descriptor detail by name.

### Method
GET

### Endpoint
/descriptors/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the descriptor.

### Response
#### Success Response (200)
- **query** (Querying object) - Querying object for further operations.

#### Response Example
```json
{
  "data": {}
}
```
```

--------------------------------

### Load iQSPR results from file

Source: https://xenonpy.readthedocs.io/en/latest/tutorials/7-inverse-design.html

Loads the previously saved iQSPR results from 'iQSPR_results_reorder.obj' using pickle.

```python
with open('iQSPR_results_reorder.obj', 'rb') as f:
    iqspr_results_reorder = pk.load(f)

```

--------------------------------

### NLLLoss 2D loss example

Source: https://xenonpy.readthedocs.io/en/latest/_modules/torch/nn/modules/loss.html

Shows how to use nn.NLLLoss with a Conv2d and LogSoftmax for 2D inputs of size N x C x height x width. The target tensor is randomly generated with values in the range 0 <= value < C. The example includes a backward pass.

```python
>>> # 2D loss example (used, for example, with image inputs)
>>> N, C = 5, 4
>>> loss = nn.NLLLoss()
>>> # input is of size N x C x height x width
>>> data = torch.randn(N, 16, 10, 10)
>>> conv = nn.Conv2d(16, C, (3, 3))
>>> m = nn.LogSoftmax(dim=1)
>>> # each element in target has to have 0 <= value < C
>>> target = torch.empty(N, 8, 8, dtype=torch.long).random_(0, C)
>>> output = loss(m(conv(data)), target)
>>> output.backward()
```

--------------------------------

### POST /methods

Source: https://xenonpy.readthedocs.io/en/latest/_modules/xenonpy/mdl/mdl.html

Creates a new method with the provided details.

```APIDOC
## POST /methods

### Description
Creates a new method.

### Method
POST

### Endpoint
/methods

### Parameters
#### Request Body
- **name** (string) - Required - The name of the method.
- **describe** (string) - Optional - Description of the method.
- **fullname** (string) - Optional - Full name of the method.

### Request Example
```json
{
  "name": "method_name",
  "describe": "description"
}
```

### Response
#### Success Response (200)
- **query** (Querying object) - Querying object for further operations.

#### Response Example
```json
{
  "data": {}
}
```
```

--------------------------------

### get_training_info

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.mdl.html

Get training information, e.g. train_loss. Returns a querying object.

```APIDOC
## get_training_info

### Description
Get training information, e.g. train_loss.

### Parameters
- **model_id** (`int`) - Required - Model id.

### Returns
Querying object.
```

--------------------------------

### get_training_env

Source: https://xenonpy.readthedocs.io/en/latest/xenonpy.mdl.html

Get model's training environments. Returns a querying object.

```APIDOC
## get_training_env

### Description
Get model's training environments.

### Parameters
- **model_id** (`int`) - Required - Model id.

### Returns
Querying object.
```