XenonPy

https://github.com/yoshida-lab/xenonpy
Admin
XenonPy is a Python library that implements a comprehensive set of machine learning tools for...
Tokens:401,842
Snippets:1,969
Trust Score:5.9
License:BSD-3-Clause
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Training progress bar output at start

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/random_nn_model_and_training.ipynb

Example output from the training progress bar at the start of training, showing 0 out of 400 epochs completed.

```text
Training:   0%|          | 0/400 [00:00<?, ?it/s]
```

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

### Training progress output at 12%

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/random_nn_model_and_training.ipynb

Example output showing training progress at 12% completion (48 out of 400 epochs) and the start of a new training run.

```text
Training:  12%|█▏        | 48/400 [00:15<02:06,  2.79it/s]
Training:   0%|          | 0/400 [00:00<?, ?it/s]
```

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

### Setup and Imports

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/predict_hypermaterials/model_training_and_vitural_screening.ipynb

Runs the tools notebook and imports necessary libraries including pandas, numpy, seaborn, matplotlib, and IPython for user-friendly printing.

```python
%run tools.ipynb

import pandas as pd
import numpy as np
import seaborn as sns
import matplotlib

from pathlib import Path
from matplotlib import pyplot as plt

# user-friendly print
from IPython.core.interactiveshell import InteractiveShell
InteractiveShell.ast_node_interactivity = "all"
```

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

### Training progress output at 10%

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/random_nn_model_and_training.ipynb

Example output showing training progress at 10% completion (42 out of 400 epochs).

```text
Training:  10%|█         | 42/400 [00:14<02:18,  2.59it/s]
```

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

### MultiStepLR scheduler example

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

Creates a MultiStepLR scheduler that decays the learning rate by gamma at epochs 30 and 80, then applies it to the optimizer and steps it each epoch.

```pycon
>>> # Assuming optimizer uses lr = 0.05 for all groups
>>> # lr = 0.05     if epoch < 30
>>> # lr = 0.005    if 30 <= epoch < 80
>>> # lr = 0.0005   if epoch >= 80
>>> scheduler = MultiStepLR(milestones=[30,80], gamma=0.1)
>>> scheduler(optimizer)
>>> for epoch in range(100):
>>>     train(...)
>>>     validate(...)
>>>     scheduler.step(),
```

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

### Training progress output at start

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/4-random_nn_model_and_training.ipynb

Shows the initial training progress output from the trainer.fit call, indicating 0 out of 400 epochs completed.

```text
Output:
Training:   0%|          | 0/400 [00:00<?, ?it/s]
```

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

### CTCLoss usage examples with padded, un-padded, and unbatched targets

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

These examples demonstrate how to use nn.CTCLoss with different target formats: padded, un-padded, and un-padded/unbatched. They show the required input shapes and the use of torch.randint for target generation.

```pycon
>>> # Target are to be padded
>>> T = 50  # Input sequence length
>>> C = 20  # Number of classes (including blank)
>>> N = 16  # Batch size
>>> S = 30  # Target sequence length of longest target in batch (padding length)
>>> S_min = 10  # Minimum target length, for demonstration purposes
>>>
>>> # Initialize random batch of input vectors, for *size = (T,N,C)
>>> input = torch.randn(T, N, C).log_softmax(2).detach().requires_grad_()
>>>
>>> # Initialize random batch of targets (0 = blank, 1:C = classes)
>>> target = torch.randint(low=1, high=C, size=(N, S), dtype=torch.long)
>>>
>>> input_lengths = torch.full(size=(N,), fill_value=T, dtype=torch.long)
>>> target_lengths = torch.randint(
...     low=S_min,
...     high=S,
...     size=(N,),
...     dtype=torch.long,
... )
>>> ctc_loss = nn.CTCLoss()
>>> loss = ctc_loss(input, target, input_lengths, target_lengths)
>>> loss.backward()
```

```pycon
>>> # Target are to be un-padded
>>> T = 50  # Input sequence length
>>> C = 20  # Number of classes (including blank)
>>> N = 16  # Batch size
>>>
>>> # Initialize random batch of input vectors, for *size = (T,N,C)
>>> input = torch.randn(T, N, C).log_softmax(2).detach().requires_grad_()
>>> input_lengths = torch.full(size=(N,), fill_value=T, dtype=torch.long)
>>>
>>> # Initialize random batch of targets (0 = blank, 1:C = classes)
>>> target_lengths = torch.randint(low=1, high=T, size=(N,), dtype=torch.long)
>>> target = torch.randint(
...     low=1,
...     high=C,
...     size=(sum(target_lengths),),
...     dtype=torch.long,
... )
>>> ctc_loss = nn.CTCLoss()
>>> loss = ctc_loss(input, target, input_lengths, target_lengths)
>>> loss.backward()
```

```pycon
>>> # Target are to be un-padded and unbatched (effectively N=1)
>>> T = 50  # Input sequence length
>>> C = 20  # Number of classes (including blank)
>>>
>>> # Initialize random batch of input vectors, for *size = (T,C)
>>> # xdoctest: +SKIP("FIXME: error in doctest")
>>> input = torch.randn(T, C).log_softmax(1).detach().requires_grad_()
>>> input_lengths = torch.tensor(T, dtype=torch.long)
>>>
>>> # Initialize random batch of targets (0 = blank, 1:C = classes)
>>> target_lengths = torch.randint(low=1, high=T, size=(), dtype=torch.long)
>>> target = torch.randint(
...     low=1,
...     high=C,
...     size=(target_lengths,),
...     dtype=torch.long,
... )
>>> ctc_loss = nn.CTCLoss()
>>> loss = ctc_loss(input, target, input_lengths, target_lengths)
>>> loss.backward()
```

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

### LambdaLR scheduler example

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

Creates a LambdaLR scheduler with two lambda functions for two optimizer groups, then applies it to the optimizer and steps it each epoch.

```pycon
>>> # Assuming optimizer has two groups.
>>> lambda1 = lambda epoch: epoch // 30
>>> lambda2 = lambda epoch: 0.95 ** epoch
>>> scheduler = LambdaLR(lr_lambda=[lambda1, lambda2])
>>> scheduler(optimizer)
>>> for epoch in range(100):
>>>     train(...)
>>>     validate(...)
>>>     scheduler.step(),
```

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

### Annealing schedule output

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/iQSPR.ipynb

Output of the annealing schedule setup: 50 steps with beta values increasing from 0.01 to 1, with the last 10 steps at beta=1.

```text
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 training information with trainer.training_info.head(5)

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/nn_model_build.ipynb

Displays the first 5 rows of the training information DataFrame, including loss and validation metrics for each epoch.

```python
trainer.training_info.head(5)
```

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

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

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/installation.rst

Creates a new conda environment named 'xenonpy' with Python 3.7 and then installs the packages listed in the cuda101.yml file. This is part of the step-by-step installation example.

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

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

### Set backend at initialization

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/dataset_and_preset.ipynb

Initializes a Dataset with the 'pickle' backend, resulting in .pkl.z file paths.

```python
# set backend at init

ds = Dataset('set1', 'set2', backend='pickle')
ds
```

```text
Result:
<Dataset> includes:
"data1": /Users/liuchang/projects/xenonpy/samples/set1/data1.pkl.z
"data2": /Users/liuchang/projects/xenonpy/samples/set2/data2.pkl.z
```

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

### Install XenonPy in development mode

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/installation.rst

Installs XenonPy in development mode: updates the Conda environment with development tools from extra_env.yml, then installs the package in editable mode.

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

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

### Get model URL strings with queryable

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/5-pre-trained_model_library.ipynb

Get only the 'url' column from the model URLs DataFrame by using the queryable specification.

```python
mdl.get_model_urls(1234, 5678)('url')
```

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

### Set up initial samples and annealing schedule for iQSPR-V

Source: https://github.com/yoshida-lab/xenonpy/blob/master/mi_book/exercise_22.ipynb

Sets up the initial SMILES samples and creates an annealing schedule for the two properties (thermal_conductivity and linear_expansion) using numpy linspace and hstack. The printed DataFrame shows the resulting beta values.

```python
# set up initial molecules for iQSPR-V
init_samples = data['SMILES'].values

# set up annealing schedule in iQSPR
beta1 = np.hstack([np.linspace(0.01,0.2,15),np.linspace(0.21,0.4,5),np.linspace(0.4,1,5),np.linspace(1,1,5)])
beta2 = np.hstack([np.linspace(0.2/15,0.2,15),np.linspace(0.21,0.4,5),np.linspace(0.4,1,5),np.linspace(1,1,5)])
beta = pd.DataFrame({'thermal_conductivity': beta1, 'linear_expansion': beta2})
print(beta)
```

```text
Output:
    thermal_conductivity  linear_expansion
0               0.010000          0.013333
1               0.023571          0.026667
2               0.037143          0.040000
3               0.050714          0.053333
4               0.064286          0.066667
5               0.077857          0.080000
6               0.091429          0.093333
7               0.105000          0.106667
8               0.118571          0.120000
9               0.132143          0.133333
10              0.145714          0.146667
11              0.159286          0.160000
12              0.172857          0.173333
13              0.186429          0.186667
14              0.200000          0.200000
15              0.210000          0.210000
16              0.257500          0.257500
17              0.305000          0.305000
18              0.352500          0.352500
19              0.400000          0.400000
20              0.400000          0.400000
21              0.550000          0.550000
22              0.700000          0.700000
23              0.850000          0.850000
24              1.000000          1.000000
25              1.000000          1.000000
26              1.000000          1.000000
27              1.000000          1.000000
28              1.000000          1.000000
29              1.000000          1.000000
```

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

### Get model download URLs by IDs

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/5-pre-trained_model_library.ipynb

Get download URLs for models by their IDs. Returns a DataFrame with columns 'id', 'etag', and 'url'.

```python
mdl.get_model_urls(1234, 5678)()
```

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

### Update XenonPy with pip install -U

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/installation.rst

Updates an existing XenonPy installation to the latest version using pip. This command is used after the environment is set up.

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

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

### BCELoss example with Sigmoid

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

Example usage of BCELoss with a sigmoid layer. It creates input and target tensors, computes the loss between the sigmoid of input and target, then performs backpropagation.

```pycon
>>> m = nn.Sigmoid()
>>> loss = nn.BCELoss()
>>> input = torch.randn(3, 2, requires_grad=True)
>>> target = torch.rand(3, 2, requires_grad=False)
>>> output = loss(m(input), target)
>>> output.backward()
```

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

### Splitter signature and docstring

Source: https://github.com/yoshida-lab/xenonpy/blob/master/mi_book/exercise_15.ipynb

Output of help(Splitter) showing the constructor parameters: size, test_size, k_fold, random_state, and shuffle. test_size can be float or int, k_fold can be int or iterable, and shuffle defaults to True.

```text
Init signature: 
Splitter(
    size: int,
    *,
    test_size: Union[float, int] = 0.2,
    k_fold: Union[int, Iterable, NoneType] = None,
    random_state: Union[int, NoneType] = None,
    shuffle: bool = True,
)
Docstring:      Data splitter for train and test
Init docstring:
Parameters
----------
size
    Total sample size.
    All data must have same length of their first dim,
test_size
    If float, should be between ``0.0`` and ``1.0`` and represent the proportion
    of the dataset to include in the test split. If int, represents the
    absolute number of test samples. Can be ``0`` if cv is ``None``.
    In this case, :meth:`~Splitter.cv` will yield a tuple only contains ``training`` and ``validation``
    on each step. By default, the value is set to 0.2.
k_fold
    Number of k-folds.
    If ``int``, Must be at least 2.
    If ``Iterable``, it should provide label for each element which will be used for group cv.
    In this case, the input of :meth:`~Splitter.cv` must be a :class:`pandas.DataFrame` object.
    Default value is None to specify no cv.
random_state
    If int, random_state is the seed used by the random number generator;
    Default is None.
shuffle
    Whether or not to shuffle the data before splitting.
File:           ~/mambaforge/envs/xepy38/lib/python3.8/site-packages/xenonpy/datatools/splitter.py
Type:           type
Subclasses:     
```

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

### Get model URLs as JSON with return_json

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/5-pre-trained_model_library.ipynb

Get model URLs as a JSON list instead of a DataFrame by setting return_json to True. Useful when you want to control the output type yourself.

```python
mdl.get_model_urls(1234, 5678)('url', return_json=True)
```

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

### Run tools.ipynb to load dependencies

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/6-transfer_learning.ipynb

Loads commonly used packages (NumPy, pandas, etc.) and in-house functions used throughout the tutorial. See the 'tools.ipynb' file for details on what is imported.

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

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

### MSELoss example

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

Example usage of the MSELoss criterion from the xenonpy.model.training.loss module. It creates an MSELoss instance, generates random input and target tensors, computes the loss, and calls backward to compute gradients.

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

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

### Initialize composition descriptor calculator

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/calculate_descriptors.ipynb

Creates a Compositions calculator instance and displays its structure.

```python
from xenonpy.descriptor import Compositions

cal = Compositions()
cal
```

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

### Show Persist extension help

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/4-random_nn_model_and_training.ipynb

Displays the help documentation for the Persist extension, showing its signature and parameters.

```python
Persist?
```

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

### Subclass BaseDescriptor with featurizers

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.descriptor.rst

Example of creating a custom descriptor class by subclassing BaseDescriptor and assigning featurizers in the constructor. The example shows four featurizer assignments, though the last three overwrite the same attribute.

```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)
```

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

### MarginRankingLoss example

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

Example usage of the MarginRankingLoss criterion from the xenonpy.model.training.loss module. It creates a MarginRankingLoss instance, generates random input tensors and a target sign tensor, computes the loss, and calls backward to compute gradients.

```pycon
>>> 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()
```

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

### Build sample data with preset.build

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorial.rst

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

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

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

### KLDivLoss usage example with batchmean reduction

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

Example usage of nn.KLDivLoss with reduction='batchmean'. The first call uses a target in probability space; the second call sets log_target=True and provides the target in log-space. Input must be in log-space.

```pycon
>>> 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)
```

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

### Set training parameters and create model directory

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/kernel_neural_network.ipynb

Sets training hyperparameters (epochs, learning rate, GPU count, display interval) and creates the model output directory.

```python
n_epoch = 3000 # epoch
lr = 0.0002 # learning rate
ngpu = 2 # number of GPU
display_interval = 100

model_path = Path(model_dir)
model_path.mkdir(exist_ok=True, parents=True)

```

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

### CTCLoss.__init__

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

Initializes the CTCLoss instance with configurable blank label, reduction method, and handling of infinite losses.

```APIDOC
## [CTCLoss] CTCLoss.__init__

### Description
Initializes the CTCLoss instance with configurable blank label, reduction method, and handling of infinite losses.

### Method
Constructor

### Endpoint
CTCLoss(blank: int = 0, reduction: str = 'mean', zero_infinity: bool = False)

### Parameters
#### Constructor Parameters
- **blank** (int) - Optional - Blank label. Default 0.
- **reduction** (str) - Optional - Specifies the reduction to apply to the output: 'none' | 'mean' | 'sum'. Default: 'mean'.
- **zero_infinity** (bool) - Optional - Whether to zero infinite losses and the associated gradients. Default: False.

### Request Example
```python
loss_fn = CTCLoss(blank=0, reduction='mean', zero_infinity=False)
```

### Response
#### Success Response
No return value. Initializes the loss function object.

#### Response Example
```python
loss_fn = CTCLoss()
```
```

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

### MDL.get_method_detail

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.mdl.rst

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: str) -> GetMethodDetail`

### Parameters
- **name** (str) - Required - Name of the method.

### Returns
Querying object of type `GetMethodDetail`.
```

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

### Initialize MDL and check version

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/5-pre-trained_model_library.ipynb

Initializes an MDL instance and displays its version. The default api_key is 'anonymous.user.key' and endpoint is 'http://xenon.ism.ac.jp/api'.

```python
mdl = MDL()
mdl

mdl.version
```

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

### Initialize Dataset with directory paths

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/dataset_and_preset.ipynb

Creates a Dataset object by passing directory paths as arguments. The resulting object lists the data files it manages.

```python
from xenonpy.datatools import Dataset

# use dir path as parameters when initlization
ds = Dataset('set1', 'set2')
ds
```

```text
Result:
<Dataset> includes:
"data1": /Users/liuchang/projects/xenonpy/samples/set1/data1.pd.xz
"data2": /Users/liuchang/projects/xenonpy/samples/set2/data2.pd.xz
```

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

### MDL.get_descriptor_detail

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.mdl.rst

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: str) -> GetDescriptorDetail`

### Parameters
- **name** (str) - Required - Name of the descriptor.

### Returns
Querying object of type `GetDescriptorDetail`.
```

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

### MDL.get_model_detail

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.mdl.rst

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: int) -> GetModelDetail`

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

### Returns
Querying object of type `GetModelDetail`.
```

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

### Set up annealing schedule with beta vector

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/7-inverse-design.ipynb

Sets up the annealing schedule for iQSPR using a beta vector. The schedule starts near 0, increases exponentially-like to 1, and includes extra steps at beta=1 for posterior exploration. The output shows the resulting 50-step beta vector.

```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)
```

```text
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.        ]
```

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

### NLLLoss usage examples

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

Shows how to use NLLLoss with a log-softmax input for a 1D classification task (N x C) and a 2D example for image inputs (N x C x height x width). The target values must be in the range [0, C).

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

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

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

### Get queryable list

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/5-pre-trained_model_library.ipynb

Retrieves the list of queryable variables that can be fetched from the server.

```python
query.queryable
```

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

### Set up model persistence and reset trainer

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/nn_model_build.ipynb

Creates a Persist object to save the model with incrementing filenames and syncs training steps. The trainer is extended with persistence and reset to the defined model.

```python
persist = Persist('test_model', increment=True, sync_training_step=True)
trainer.extend(persist)
trainer.reset(to=model)
```

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

### Check XenonPy version

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/tutorials/7-inverse-design.ipynb

Checks the installed XenonPy version. The expected output is '0.6.2'.

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

```text
Result:
'0.6.2'
```

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

### Sample output from loading benchmark data

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/CSP_with_element_substitution.ipynb

Shows the first three rows of the searching_targets dataframe after loading. Columns include composition, elements, number of atoms, space group, volume, structure, formation energy, and predicted properties.

```text
Result:
                      composition  elements  n_elemets  n_atoms  \
mp-569304              {'C': 4.0}       [C]          1        4   
mp-149                {'Si': 2.0}      [Si]          1        2   
mp-2534    {'Ga': 1.0, 'As': 1.0}  [Ga, As]          2        2   

          pretty_formula space_group  space_group_number     volume  \
mp-569304              C        R-3m                 166  62.601036   
mp-149                Si       Fd-3m                 227  40.888293   
mp-2534             GaAs       F-43m                 216  47.531857   

                                                   structure full_formula  \
mp-569304  [[ 3.48460258  2.02633463 33.51650787] C, [1.0...           C4   
mp-149     [[1.11629943 0.7893429  1.93348733] Si, [0. 0....          Si2   
mp-2534    [[0. 0. 0.] Ga, [3.52125296 2.48990185 6.09898...       Ga1As1   

           formation_energy  dataset  pred_volume  pred_spg  \
mp-569304          0.000000        1    14.695088       166   
mp-149             0.000000        1    33.270061       225   
mp-2534           -0.347249        1    41.831081       216   

                                              pred_spg_top20  rank  
mp-569304  [166, 64, 194, 15, 62, 8, 160, 225, 221, 74, 1...     0   
mp-149     [225, 227, 189, 194, 200, 129, 216, 191, 11, 1...     1   
mp-2534    [216, 225, 160, 187, 166, 14, 5, 194, 44, 156,...     0  
```

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

### Clone XenonPy repository

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/installation.rst

Clones the XenonPy repository from GitHub to prepare for development-mode installation.

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

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

### Load reactor and create ReactantPool

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/iSMD.ipynb

Loads a pre-trained reactor model and creates a ReactantPool for proposal. The output shows the time taken to load the model and initialize the pool.

```python
%%time
from xenonpy.contrib.ismd import ReactantPool
from xenonpy.contrib.ismd import load_reactor

model_path = os.path.join(assets_path,'STEREO_separated_augm_model_average_20.pt')
mol_reactor = load_reactor(model_path=model_path, device_id=-1)
mol_pool = ReactantPool(pool_df=reactant_pool, sim_df=sim_df, reactor=mol_reactor)
```

```text
Output:
CPU times: user 1.03 s, sys: 61.8 ms, total: 1.09 s
Wall time: 136 ms
```

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

### Configure Trainer with optimizer and loss

Source: https://github.com/yoshida-lab/xenonpy/blob/master/samples/nn_model_build.ipynb

Sets up a Trainer instance for the CGCNN model with Adam optimizer, MSE loss, exponential learning rate scheduler, and gradient clipping.

```python
trainer = Trainer(
    model=cgcnn,
    optimizer=Adam(lr=0.0005),
    loss_func=MSELoss(),
    lr_scheduler=ExponentialLR(gamma=0.99),
    clip_grad=ClipNorm(max_norm=0.04)
)
```

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

### Get valid unique SMILES

Source: https://github.com/yoshida-lab/xenonpy/blob/master/xenonpy/contrib/sample_codes/Fragment_Ngram/Fragment_Ngram.ipynb

Extracts unique SMILES strings that passed the convertibility check.

```python
smiles_list = list(data['SMILES'][check].unique())
```

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

### xenonpy.utils.useful_cls.Timer

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.utils.rst

A class for timing code execution. It provides start and stop methods and an elapsed property.

```APIDOC
## Timer

### Description
A class for timing code execution.

### Constructor
`Timer(time_func=<built-in function perf_counter>)`

### Methods
#### start(fn_name='main')
Start timing for the given function name.

#### stop(fn_name='main')
Stop timing for the given function name.

### Properties
#### elapsed
Get the elapsed time.
```

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

### MinPooling

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.descriptor.rst

Documentation for the MinPooling class, its constructor, methods, and properties.

```APIDOC
## MinPooling

### Description
MinPooling is a composition featurizer that computes the minimum pooling of elemental properties for a compound. It inherits from BaseCompositionFeaturizer and can be used to generate features for machine learning models.

### Constructor
`MinPooling(elemental_info: DataFrame | None = None, n_jobs: int = -1, on_errors: str = 'raise', return_type: str = 'any', target_col: List[str] | str | None = None)`

#### Parameters
- **elemental_info** (DataFrame | None) - Optional - Elemental level information for each element. Defaults to XenonPy embedded information.
- **n_jobs** (int) - Optional - Number of jobs to run in parallel for fit and predict. Set -1 to use all CPU cores (default).
- **on_errors** (str) - Optional - How to handle exceptions in feature calculations. Can be 'nan', 'keep', or 'raise'. Default is 'raise'.
- **return_type** (str) - Optional - Return type: 'any', 'array', or 'df'. Default is 'any'.
- **target_col** (List[str] | str | None) - Optional - Column to use for transformation when input is a DataFrame. If None, all columns are used.

### Methods

#### mix_function(elems, nums)

##### Description
Computes the minimum pooling descriptor for a compound given its elements and their counts.

##### Parameters
- **elems** (list) - Required - Elements in the compound.
- **nums** (list) - Required - Number of each element.

##### Returns
- **descriptor** (numpy.ndarray) - The computed descriptor.

#### set_transform_request(entries='$UNCHANGED$', return_type='$UNCHANGED$', target_col='$UNCHANGED$')

##### Description
Configures metadata routing for the `transform` method. This is relevant when the estimator is used as a sub-estimator in a meta-estimator with metadata routing enabled.

##### Parameters
- **entries** (str, True, False, or None) - Optional - Metadata routing for `entries` parameter in `transform`.
- **return_type** (str, True, False, or None) - Optional - Metadata routing for `return_type` parameter in `transform`.
- **target_col** (str, True, False, or None) - Optional - Metadata routing for `target_col` parameter in `transform`.

##### Returns
- **self** (object) - The updated object.

#### feature_labels (property)

##### Description
Generates attribute labels for the features.

##### Returns
- **labels** (list of str) - Attribute labels.
```

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

### NLLLoss

Source: https://github.com/yoshida-lab/xenonpy/blob/master/docs/source/xenonpy.model.training.rst

Documentation for the NLLLoss class, including its constructor parameters, forward method, and usage examples.

```APIDOC
## NLLLoss

### Description
Negative log likelihood loss. It is useful to train a classification problem with C classes. If provided, the optional argument weight should be a 1D Tensor assigning weight to each of the classes. This is particularly useful when you have an unbalanced training set.

### Class
`xenonpy.model.training.loss.NLLLoss`

### Parameters
- **weight** (Tensor, optional) – a manual rescaling weight given to each class. If given, it has to be a Tensor of size C. Otherwise, it is treated as if having all ones.
- **size_average** (bool, optional) – Deprecated (see `reduction`). By default, the losses are averaged over each loss element in the batch. Note that for some losses, there are multiple elements per sample. If the field `size_average` is set to `False`, the losses are instead summed for each minibatch. Ignored when `reduce` is `False`. Default: `True`
- **ignore_index** (int, optional) – Specifies a target value that is ignored and does not contribute to the input gradient. When `size_average` is `True`, the loss is averaged over non-ignored targets. Default: -100
- **reduce** (bool, optional) – Deprecated (see `reduction`). By default, the losses are averaged or summed over observations for each minibatch depending on `size_average`. When `reduce` is `False`, returns a loss per batch element instead and ignores `size_average`. Default: `True`
- **reduction** (str, optional) – Specifies the reduction to apply to the output: `'none'` | `'mean'` | `'sum'`. `'none'`: no reduction will be applied, `'mean'`: the sum of the output will be divided by the number of elements in the output, `'sum'`: the output will be summed. Note: `size_average` and `reduce` are in the process of being deprecated, and in the meantime, specifying either of those two args will override `reduction`. Default: `'mean'`

### Methods
#### forward(input: Tensor, target: Tensor) → Tensor
Runs the forward pass.

### Attributes
- **ignore_index** (int)

### Example
```pycon
>>> log_softmax = nn.LogSoftmax(dim=1)
>>> loss_fn = nn.NLLLoss()
>>> # input to NLLLoss is of size N x C = 3 x 5
>>> input = torch.randn(3, 5, requires_grad=True)
>>> # each element in target must have 0 <= value < C
>>> target = torch.tensor([1, 0, 4])
>>> loss = loss_fn(log_softmax(input), target)
>>> loss.backward()
>>>
>>>
>>> # 2D loss example (used, for example, with image inputs)
>>> N, C = 5, 4
>>> loss_fn = nn.NLLLoss()
>>> data = torch.randn(N, 16, 10, 10)
>>> conv = nn.Conv2d(16, C, (3, 3))
>>> log_softmax = nn.LogSoftmax(dim=1)
>>> # output of conv forward is of shape [N, C, 8, 8]
>>> output = log_softmax(conv(data))
>>> # each element in target must have 0 <= value < C
>>> target = torch.empty(N, 8, 8, dtype=torch.long).random_(0, C)
>>> # input to NLLLoss is of size N x C x height (8) x width (8)
>>> loss = loss_fn(output, target)
>>> loss.backward()
```
```
Tokens:
Raw