HomCloud

https://homcloud.dev
Admin
HomCloud is a data analysis software based on persistent homology for topological data analysis of...
Tokens:128,449
Snippets:1,172
Trust Score:5.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Self-check output example

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu.en.html

Expected output format upon successful installation.

```text
HomCloud version: 4.4.0
Python version: 3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0]
CGAL version: 5.6 (1050601000)
Alpha Shape 3 ... ok
Alpha Shape 3 with weights ... ok
Periodic Alpha Shape 3 with weights ... ok
Alpha Shape 2 ... ok
Grayscale 2D bitmap ... ok
Binary 2D bitmap ... ok
Binary 2D periodic bitmap ... ok
Rips filtration ... ok
Plotting PD ... ok
Optimal Volume ... ok
PyVista 3D drawing (close the pop-up window)... ok
```

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

### Get Example Data in HomCloud

Source: https://homcloud.dev/python-api/_modules/homcloud/interface.html

Retrieves predefined example datasets. Currently supports 'tetrahedron', 'bitmap_01_5x5x5', and 'bitmap_levels_5x5'.

```python
import homcloud.interface as hc
print(hc.example_data("tetrahedron"))
```

```python
import homcloud.interface as hc
print(hc.example_data("tetrahedron"))
```

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

### GET /example_data

Source: https://homcloud.dev/python-api/_modules/homcloud/interface.html

Retrieves predefined example datasets for testing and demonstration purposes.

```APIDOC
## GET /example_data

### Description
Returns specific example datasets based on the provided name.

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the example dataset (e.g., "tetrahedron", "bitmap_01_5x5x5", "bitmap_levels_5x5").

### Response
#### Success Response (200)
- **data** (numpy.ndarray) - The requested dataset.

### Response Example
{
  "data": [[0.0, 0.0, 0.0], [8.0, 0.0, 0.0], [5.0, 6.0, 0.0], [4.0, 2.0, 6.0]]
}
```

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

### Install Jupyter for Tutorials

Source: https://homcloud.dev/install-guide/install_guide_for_Windows.en.html

Install Jupyter Notebook, which is required to run the HomCloud tutorials.

```bash
pip install jupyter

```

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

### Install Dependencies

Source: https://homcloud.dev/py-tutorial/analysis_of_atomic_configurations_1_en.html

Install the required ASE and py3Dmol libraries.

```bash
pip3 install ase py3Dmol
```

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

### Start Jupyter Notebook

Source: https://homcloud.dev/install-guide/install_guide_for_Windows.en.html

Navigate to the directory where the tutorial files were extracted and start the Jupyter Notebook server.

```bash
jupyter notebook

```

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

### HomCloud Self-Check Output Example

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu_venv.en.html

Example output indicating a successful HomCloud installation, including version information and status of various internal checks.

```text
HomCloud version: 4.0.0
Python version: 3.10.6 (main, Mar 10 2023, 10:55:28) [GCC 11.3.0]
Alpha Shape 3 ... ok
Alpha Shape 3 with weights ... ok
Periodic Alpha Shape 3 with weights ... ok
Alpha Shape 2 ... ok
Grayscale 2D bitmap ... ok
Binary 2D bitmap ... ok
Binary 2D periodic bitmap ... ok
Rips filtration ... ok
Plotting PD ... ok
Optimal Volume ... ok
PyVista 3D drawing (close the pop-up window)... ok
```

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

### Install HomCloud

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu.en.html

Install the latest or a specific version of HomCloud.

```bash
pip3 install --user homcloud
```

```bash
pip3 install --user homcloud==3.6.0
```

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

### Launch Jupyter Notebook

Source: https://homcloud.dev/install-guide/install_guide_for_M1Mac.en.html

Starts the Jupyter notebook server to run tutorials.

```bash
jupyter notebook
```

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

### Install dependencies via Homebrew

Source: https://homcloud.dev/install-guide/install_guide_for_M1Mac.en.html

Installs Python and CGAL using the Homebrew package manager.

```bash
brew install python cgal
```

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

### example_data

Source: https://homcloud.dev/python-api/interface.html

Retrieves example datasets provided by the library.

```APIDOC
## FUNCTION example_data

### Description
Returns example data. Returns the tetrahedron 3D pointcloud for name == "tetrahedron".

### Parameters
- **name** (string) - Required - Name of the data.

### Response
- **Return Type** (numpy.ndarray) - The requested example data.
```

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

### Install Python Packages and HomCloud

Source: https://homcloud.dev/install-guide/install_guide_for_Windows.en.html

Install necessary packages like numpy, pyqt, pyvista, and HomCloud within the activated virtual environment.

```bash
pip install "numpy<2" pyqt5 pyqt6 wheel "pyvista[all,trame]" pyvistaqt 
pip install homcloud

```

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

### Install system dependencies via apt

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu.en.html

Install required Debian packages using apt-get.

```bash
sudo apt-get install libcgal-dev libpython3-dev python3-matplotlib python3-numpy python3-scipy python3-pip python3-msgpack python3-pulp python3-sklearn paraview python3-paraview jupyter
```

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

### Install HomCloud and Dependencies

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu_venv.en.html

Installs the 'wheel' package, which is often a prerequisite for installing other Python packages, followed by the 'homcloud' package with recommended extras.

```bash
pip install wheel
pip install "homcloud[recommended]"
```

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

### Retrieve Example Data

Source: https://homcloud.dev/python-api/interface.html

Fetches sample datasets by name, such as the tetrahedron 3D pointcloud.

```python
>>> import homcloud.interface as hc
>>> hc.example_data("tetrahedron")
array([[ 0.,  0.,  0.],
       [ 8.,  0.,  0.],
       [ 5.,  6.,  0.],
       [ 4.,  2.,  6.]])
```

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

### Update and Install Debian Packages

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu_venv.en.html

Installs required development packages for Python and venv using apt-get. Ensure your package list is up-to-date before installation.

```bash
sudo apt-get update
sudo apt-get install python3-all-dev python3-venv
```

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

### Install HomCloud

Source: https://homcloud.dev/install-guide/install_guide_for_M1Mac.en.html

Installs the HomCloud package with specific environment variables for Homebrew paths.

```bash
CPLUS_INCLUDE_PATH=/opt/homebrew/include LIBRARY_PATH=/opt/homebrew/lib pip install homcloud
```

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

### Install Python dependencies via pip

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu.en.html

Install necessary Python packages using pip3.

```bash
pip3 install --user wheel Cython "pyvista[all,trame]" pyqt6 pyvistaqt
pip3 install --user ripser
```

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

### Install Dipha for High-Dimensional Data

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu_venv.en.html

Optional steps to install Dipha, a tool for computing persistent homology on more than 4-dimensional voxel data. This involves installing prerequisites, downloading, building, and copying the executable.

```bash
sudo apt-get install openmpi-bin libopenmpi-dev cmake
```

```bash
cmake .
make
```

```bash
python3 -m homcloud.self_check --dipha
```

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

### Self-check output

Source: https://homcloud.dev/install-guide/install_guide_for_M1Mac.en.html

Expected output format upon successful installation.

```text
HomCloud version: 4.0.0a4
Python version: 3.11.2 (main, Mar 24 2023, 00:16:47) [Clang 14.0.0 (clang-1400.0.29.202)]
Alpha Shape 3 ... ok
Alpha Shape 3 with weights ... ok
Periodic Alpha Shape 3 with weights ... ok
Alpha Shape 2 ... ok
Grayscale 2D bitmap ... ok
Binary 2D bitmap ... ok
Binary 2D periodic bitmap ... ok
Rips filtration ... ok
Plotting PD ... ok
Optimal Volume ... ok
PyVista 3D drawing (close the pop-up window)... ok
```

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

### Install Python packages

Source: https://homcloud.dev/install-guide/install_guide_for_M1Mac.en.html

Installs the necessary Python dependencies for HomCloud within the active virtual environment.

```bash
 pip install "numpy<2" wheel jupyter Cython "pyvista[trame,all]" pyqt6 pyvistaqt
```

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

### Run HomCloud self-check

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu.en.html

Verify the installation by running the self-check program.

```bash
python3 -m homcloud.self_check --pyvista
```

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

### Initialize virtual environment

Source: https://homcloud.dev/install-guide/install_guide_for_M1Mac.en.html

Navigates to the project directory and creates a Python virtual environment.

```bash
cd homcloud
python3 -m venv venv
```

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

### Compute PDList from Alpha Filtration

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Example usage of the alpha filtration method to generate a PDList from a pointcloud.

```python
>>> import homcloud.interface as hc
>>> pointcloud = hc.example_data("tetrahedron")
>>> hc.PDList.from_alpha_filtration(pointcloud)
-> Returns a new PDList
```

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

### Run HomCloud Self-Check Program

Source: https://homcloud.dev/install-guide/install_guide_for_Windows.en.html

Execute the self-checking program to verify a successful installation. A PyVista 3D window will open and should be closed.

```bash
python -m homcloud.self_check --pyvista

```

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

### Get Birth Position of Optimal Volume

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/optimal_volume.html

Retrieves the birth simplex of an optimal volume. Supports various return formats including default, coordinates, symbols, and vertex indexes. Use to identify the starting simplex of the volume.

```python
def birth_position(self, by="default"):
        """
        Args:
            by (string): Format of return values, "default", "coordinates", "symbols", "vertex_indexes", or "vindexes"

        Returns:
            simplex: The birth simplex.
        """
        return self.get_geometry_resolver(by).resolve_cell(self.pair.birth_index)

    #: The alias of :meth:`birth_position`.
    birth_pos = birth_position
```

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

### PCA Initialization and Fitting

Source: https://homcloud.dev/py-tutorial/ml_pc_en.html

Demonstrates how to initialize and fit a PCA model to data.

```APIDOC
## POST /api/pca

### Description
Initializes and fits a Principal Component Analysis (PCA) model to the provided data.

### Method
POST

### Endpoint
/api/pca

### Parameters
#### Request Body
- **pdvects** (array) - Required - The input data vectors for PCA.
- **n_components** (int or float or 'mle') - Optional - Number of components to keep. Defaults to 'mle' if not specified.
- **copy** (bool) - Optional - Whether to copy data. Defaults to True.
- **whiten** (bool) - Optional - Whether to whiten the data. Defaults to False.
- **svd_solver** (string) - Optional - The algorithm to use for SVD. Defaults to 'auto'.
- **tol** (float) - Optional - Tolerance for singular values. Defaults to 0.0.
- **iterated_power** (int or 'auto') - Optional - Number of iterations for the power method. Defaults to 'auto'.
- **n_oversamples** (int) - Optional - Additional number of random vectors for randomized SVD. Defaults to 10.

### Request Example
```json
{
  "pdvects": [[1, 2, 3], [4, 5, 6]],
  "n_components": 2,
  "whiten": true
}
```

### Response
#### Success Response (200)
- **pca_model** (object) - The fitted PCA model object.

#### Response Example
```json
{
  "pca_model": {
    "n_components": 2,
    "whiten": true,
    "components": [[...], [...]]
  }
}
```
```

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

### Import required libraries for machine learning

Source: https://homcloud.dev/py-tutorial/ml_pc_en.html

Initializes the environment with HomCloud, NumPy, scikit-learn, and PyVista for data analysis and visualization.

```python
import os
import homcloud.interface as hc 
import numpy as np
from tqdm.notebook import tqdm  # For progressbar
import matplotlib.pyplot as plt
import sklearn.linear_model as lm  # for rogistic regression
from sklearn.decomposition import PCA  # for PCA
from sklearn.model_selection import train_test_split
import pyvista as pv  # for 3D visualization
```

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

### Create and Navigate to Working Directory

Source: https://homcloud.dev/install-guide/install_guide_for_Windows.en.html

Use these commands in the command prompt to create a directory for HomCloud and navigate into it.

```bash
mkdir homcloud
cd homcloud

```

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

### PDList Initialization and File Handling

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Details on how to initialize a PDList object and manage its associated file resources.

```APIDOC
## PDList Class

### Description
Collection of 0th, 1st, ..., and q-th persistence diagrams. In HomCloud, diagrams for all degrees coming from a filtration are combined into a single file. This class is the interface to the file.

### Parameters
#### `__init__` Parameters
- **file** (string or file) - The pathname to a diagram file.
- **filetype** (enum PDList.FileType) - Ignored, for backward compatibility.
- **cache** (bool) - Ignored (for backward compatibility).
- **negate** (bool) - Ignored (for backward compatibility).

### Methods
#### `close()`
Dispose PDList object and release resources.

#### `__enter__()`
Context manager entry point.

#### `__exit__(exception_type, exception_value, traceback)`
Context manager exit point, ensures resources are released.

#### `pdgm_id` (property)
Returns the PDGM ID from the reader.

#### `compute_pd(filtration, save_to, parallels, algorithm, save_suppl_info)` (static method)
Computes the persistence diagram for a given filtration and saves it to a file.

#### `open_pdgm_file(save_to)` (static method)
Opens a file for writing persistence diagrams. Returns an in-memory BytesIO object if `save_to` is None.

#### `from_alpha_filtration(...)` (static method)
Compute PDList by using an alpha filtration from a point cloud.
```

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

### Import HomCloud and Visualization Libraries

Source: https://homcloud.dev/py-tutorial/pointcloud_3d_visualization_by_plotly_en.html

Initializes the environment by importing HomCloud, NumPy, Matplotlib, and Plotly for 3D data processing and visualization.

```python
import homcloud.interface as hc  # HomCloud interface
import numpy as np
import matplotlib.pyplot as plt
import homcloud.plotly_3d as p3d  # For 3D visualization
import plotly.graph_objects as go  # For 3D visualization
import plotly.io
plotly.io.renderers.default = 'notebook'  # plotly Setting. Choose your favorite renderer.
```

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

### GET /histogram

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Generates a histogram of the persistence diagram.

```APIDOC
## GET /histogram

### Description
Returns the histogram of the PD.

### Parameters
#### Query Parameters
- **x_range** (tuple[float, float]) - Optional - The lower and upper range of the bins on x-axis.
- **x_bins** (int) - Optional - The number of bins on x-axis.
- **y_range** (tuple[float, float]) - Optional - The lower and upper range of the bins on y-axis.
- **y_bins** (int) - Optional - The number of bins on y-axis.

### Response
#### Success Response (200)
- **histogram** (object) - The Histogram object.
```

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

### Importing Libraries and Setting Visualization Backend

Source: https://homcloud.dev/py-tutorial/pointcloud_pbc_en.html

Initializes the HomCloud interface, PyVista for visualization, and numerical libraries. Sets the PyVista backend to static for Jupyter environments.

```python
import homcloud.interface as hc  # HomCloud interface
import pyvista as pv  # PyVista for 3D visualization
import numpy as np
import matplotlib.pyplot as plt
```

```python
# PyVista's backend. If you want interactive plot, change 'static' to 'trame'
pv.set_jupyter_backend('static')
```

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

### Create a Virtual Environment with venv

Source: https://homcloud.dev/install-guide/install_guide_for_Windows.en.html

Create a lightweight virtual environment using Python 3.11. Ensure the environment folder name is alphanumeric.

```bash
py -3.11 -m venv venv311

```

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

### GET /birth_positions_by

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Retrieves birth positions in a specified format.

```APIDOC
## GET /birth_positions_by

### Description
Return the birth positions in the specified form.

### Parameters
#### Query Parameters
- **by** (string) - Optional - Format of return values: "default", "coordinates", "symbols", "vertex_indexes", or "vindexes"

### Response
#### Success Response (200)
- **simplices** (list) - The birth simplices in the requested form
```

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

### GET /show_slice3d

Source: https://homcloud.dev/python-api/_modules/homcloud/interface.html

Displays slices of 3D bitmap data.

```APIDOC
## GET /show_slice3d

### Description
Display slices of 3D bitmap data.

### Method
GET

### Parameters
#### Query Parameters
- **volumes** (list) - Required - Multiple 3D bitmap data.
- **slice** (int) - Optional - The direction of slicing: 0, 1, or 2 for z, y, x direction.
- **spacer** (int) - Optional - The number of pixels between horizontally aligned slices.
- **range** (tuple) - Optional - Range of slices.
- **image_viewer** (string) - Optional - Command to open the image viewer.
```

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

### Initialize and Style 3D Visualization

Source: https://homcloud.dev/py-tutorial/analysis_of_atomic_configurations_1_en.html

Initialize a py3Dmol viewer, add molecular data in XYZ format, and apply styles for sticks and spheres. This prepares the visualization of the atomic structure.

```python
view = py3Dmol.view()
view.addModel(cu_triangle_atoms_xyz_data, "xyz")
view.setStyle({'stick': {"colorscheme": "default"}})
view.addStyle({"sphere": {"scale": 0.3}})
view.zoomTo()
view.show()
```

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

### Load and Visualize 1D Persistence Diagram (with PBC)

Source: https://homcloud.dev/py-tutorial/pbc_bitmap_en.html

Loads a persistence diagram computed with periodic boundary conditions and visualizes its 1-dimensional features. This allows comparison with diagrams computed without PBC.

```python
pdlist_pbc = hc.PDList("bitmap_pbc.pdgm")
pd1_pbc = pdlist_pbc.dth_diagram(1)
```

```python
pd1_pbc.histogram(x_bins=28).plot(colorbar={"type":"log"})
```

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

### StableVolume Initialization and Logic

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/bitmap_phtrees.html

Initializes a stable volume and checks for unstable children based on epsilon.

```python
def __init__(self, node, epsilon):
    self.node = node

    self._volume = set(tuple(p) for p in node.dic["volume"])
    for child_id in node.dic["children"]:
        child_dic = node.mt.treedict["nodes"][child_id]
        if self.is_unstable_child(child_dic, epsilon):
            self._volume.difference_update(tuple(p) for p in child_dic["volume"])
```

```python
def is_unstable_child(self, child_dic, epsilon):
    is_sublevel = not self.node.mt.is_superlevel
    is_lower = self.node.mt.degree() == 0
    if is_lower and is_sublevel:

```

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

### Configure Initial Radii

Source: https://homcloud.dev/py-tutorial/pointcloud_en.html

Prepare weights array for particles with specific radii, using squared values.

```python
weights = np.concatenate([np.full(500, 0.001), np.full(500, 0.005)])
```

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

### GET /nearest_pair_to

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Finds the birth-death pair closest to a given coordinate.

```APIDOC
## GET /nearest_pair_to

### Description
Returns a pair closest to (x, y).

### Parameters
#### Query Parameters
- **x** (float) - Required - X (birth) coordinate.
- **y** (float) - Required - Y (death) coordinate.

### Response
#### Success Response (200)
- **pair** (object) - The closest pair.
```

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

### GET /birth_death_times

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Retrieves the birth and death times for the persistence diagram.

```APIDOC
## GET /birth_death_times

### Description
Returns the birth times and death times of the persistence diagram.

### Response
#### Success Response (200)
- **births** (numpy.ndarray) - Array of birth times
- **deaths** (numpy.ndarray) - Array of death times
```

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

### HomCloud Python API Initialization

Source: https://homcloud.dev/python-api/_sources/outline.rst.txt

How to import and initialize the HomCloud Python API.

```APIDOC
## Importing HomCloud API

### Description
To use the HomCloud API from Python, you need to import the `interface` module.

### Code Example
```python
import homcloud.interface as hc
```
```

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

### Activate the Virtual Environment

Source: https://homcloud.dev/install-guide/install_guide_for_Windows.en.html

Enter the created virtual environment. This command must be run every time a new command prompt is launched.

```bash
venv311\Scripts\activate

```

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

### GET /pdlist/bitmap_phtrees

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Reads a BitmapPHTrees object associated with a specific degree.

```APIDOC
## GET /pdlist/bitmap_phtrees

### Description
Reads a BitmapPHTrees object computed by BitmapPHTrees.for_bitmap_levelset.

### Method
GET

### Endpoint
/pdlist/bitmap_phtrees

### Parameters
#### Query Parameters
- **degree** (int) - Required - The PD degree (0 or n-1).
```

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

### GET /pdlist/diagram

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Retrieves a specific d-th persistence diagram from the PDList.

```APIDOC
## GET /pdlist/diagram

### Description
Returns the d-th persistence diagram from the PDList object.

### Method
GET

### Endpoint
/pdlist/diagram

### Parameters
#### Query Parameters
- **d** (int) - Required - The degree of the diagram.
- **load_indexed_pairs** (bool) - Optional - If true, index information is loaded to reduce loading time.
```

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

### Extract Atomic Coordinates

Source: https://homcloud.dev/py-tutorial/analysis_of_atomic_configurations_1_en.html

Get the positions of the atoms in the repeated structure.

```python
atoms_positions = cu_atoms_4.get_positions()
```

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

### Visualize SiO2 Structure with Edges

Source: https://homcloud.dev/py-tutorial/analysis_of_atomic_configurations_2_en.html

Initializes a py3Dmol view, adds the SiO2 model, sets styles for sticks and spheres with opacity, and then adds green edges to represent the boundary of a stable volume. Finally, it zooms and displays the view.

```python
view.addStyle({"sphere": {"scale": 0.3, "opacity": 0.8}})  # ボールの部分も半透明で
py3dmolhelper.add_edges(view, stable_volume.boundary(), "green", 0.4)

view.zoomTo()
view.show()
```

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

### Get All Birth-Death Pairs

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Returns a list of all birth-death pairs in the Persistence Diagram.

```python
return [self.pair(n) for n in range(self.pd.num_pairs)]
```

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

### Create working directory

Source: https://homcloud.dev/install-guide/install_guide_for_M1Mac.en.html

Creates a new directory named homcloud to serve as the project root.

```bash
mkdir homcloud
```

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

### GET /boundary_loop

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/optimal_volume.html

Retrieves the boundary loop of a 2D volume as a list of points.

```APIDOC
## GET /boundary_loop

### Description
Returns the list of points in the loop order for a 2D volume. Returns None if the boundary consists of multiple loops.

### Method
GET

### Endpoint
/boundary_loop

### Parameters
#### Query Parameters
- **by** (string) - Optional - Format of return values: "default", "coordinates", "symbols", "vertex_indexes", or "vindexes".
- **adjust_periodic_boundary** (Option[(float, float)]) - Optional - Periodic boundary treatment.

### Response
#### Success Response (200)
- **loop** (list) - The list of points in the loop order.
```

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

### Initialize and Fit PCA

Source: https://homcloud.dev/py-tutorial/ml_pc_3d_visualization_by_plotly_en.html

Initialize PCA with 2 components and fit it to the persistence diagram vectors. This reduces the data to a 2D space for visualization.

```python
pca = PCA(n_components=2)
pca.fit(pdvects)
```

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

### Get Optimal Volume

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/phtrees.html

Returns the volume nodes associated with the optimal volume.

```python
def volume(self):
    return self.volume_nodes
```

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

### HomCloud Self-Check Output

Source: https://homcloud.dev/install-guide/install_guide_for_Docker.en.html

Expected output confirming successful installation of HomCloud and its components.

```text
HomCloud version: 4.4.1
Python version: 3.12.2 (main, Mar 12 2024, 11:13:18) [GCC 12.2.0]
CGAL version: 5.6.1 (1050611000)
Alpha Shape 3 ... ok
Alpha Shape 3 with weights ... ok
Periodic Alpha Shape 3 with weights ... ok
Alpha Shape 2 ... ok
Grayscale 2D bitmap ... ok
Binary 2D bitmap ... ok
Binary 2D periodic bitmap ... ok
Rips filtration ... ok
Plotting PD ... ok
Optimal Volume ... ok
```

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

### Import BackgroundPlotter

Source: https://homcloud.dev/py-tutorial/pointcloud_en.html

Import the BackgroundPlotter module from pyvistaqt.

```python
import pyvistaqt as pvqt
```

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

### Initialize and fit PCA model

Source: https://homcloud.dev/py-tutorial/ml_pc_en.html

Configure PCA to reduce data to two components and fit the model to the provided vector data.

```python
pca = PCA(n_components=2)
pca.fit(pdvects)
```

```python
PCA(n_components=2)
```

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

### Configure colorbar specifications

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/histogram.html

Static method to map dictionary configurations to ZSpec objects for plotting.

```python
    @staticmethod
    def _zspec(colorbar):
        ztype = colorbar.get("type", "linear")
        vmax = colorbar.get("max")
        vmin = colorbar.get("min")
        label = colorbar.get("label")
        if "colormap" in colorbar:
            colormap = plt.get_cmap(colorbar["colormap"])
        else:
            colormap = None
        if ztype == "linear":
            return plot_PD.ZSpec.Linear(vmax, vmin, colormap, label)
        elif ztype == "log":
            return plot_PD.ZSpec.Log(vmax, vmin, colormap, label)
        elif ztype == "loglog":
            return plot_PD.ZSpec.LogLog(vmax, vmin, colormap, label)
        elif ztype == "linear-midpoint":
            return plot_PD.ZSpec.LinearMidPoint(colorbar["midpoint"], vmax, vmin, colormap, label)
        elif ztype == "power":
            return plot_PD.ZSpec.Power(colorbar["p"], vmax, vmin, colormap, label)
        else:
            raise RuntimeError("unknown colorbar type: {}").format(ztype)
```

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

### GET /pair_node_nearest_to

Source: https://homcloud.dev/python-api/interface.html

Retrieves the node corresponding to the birth-death pair nearest to the specified coordinates.

```APIDOC
## GET /pair_node_nearest_to

### Description
Return the node corresponding the pair which is nearest to (x, y).

### Parameters
#### Query Parameters
- **x** (float) - Required - The birth-axis coordinate.
- **y** (float) - Required - The death-axis coordinate.

### Response
#### Success Response (200)
- **node** (PHTrees.Node) - The nearest node.
```

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

### Jupyter Lab Startup Output

Source: https://homcloud.dev/install-guide/install_guide_for_Docker.en.html

Expected console output when Jupyter Lab initializes successfully.

```text
[I 2024-03-27 17:22:36.766 ServerApp] jupyter_lsp | extension was successfully linked.
[I 2024-03-27 17:22:36.766 ServerApp] jupyter_server_proxy | extension was successfully linked.
      :
      :
[I 2024-03-27 17:22:37.041 ServerApp]     http://127.0.0.1:8888/lab
[I 2024-03-27 17:22:37.041 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[I 2024-03-27 17:22:37.053 ServerApp] Skipped non-installed server(s): bash-language-server, dockerfile-language-server-nodejs, javascript-typescript-langserver, jedi-language-server, julia-language-server, pyright, python-language-server, python-lsp-server, r-languageserver, sql-language-server, texlab, typescript-language-server, unified-language-server, vscode-css-languageserver-bin, vscode-html-languageserver-bin, vscode-json-languageserver-bin, yaml-language-server
```

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

### Get Pair Degree

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Returns the degree of the pair, which indicates the dimension of the homology class.

```python
return self.diagram.degree
```

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

### Visualize Optimal Volume (Basic)

Source: https://homcloud.dev/py-tutorial/pointcloud_pbc_en.html

Visualize the computed optimal volume using PyVista. This basic visualization may not explicitly show periodic boundary adjustments.

```python
pl = pv.Plotter()
pl.add_mesh(optimal_volume.to_pyvista_boundary_mesh())
pl.show()
```

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

### GET /cells

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/optimal_volume.html

Retrieves all cells in volume optimal cycles with customizable return formats.

```APIDOC
## GET /cells

### Description
Retrieves all cells in volume optimal cycles. The return format can be specified via the 'by' parameter.

### Method
GET

### Endpoint
/cells

### Parameters
#### Query Parameters
- **by** (string) - Optional - Format of return values: "default", "coordinates", "symbols", "vertex_indexes", or "vindexes".
- **adjust_periodic_boundary** (Option[(float, float)]) - Optional - Periodic boundary treatment.

### Response
#### Success Response (200)
- **cells** (list) - All cells in volume optimal cycles.
```

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

### Get Boundary Points

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/phtrees.html

Retrieves all vertices that form the boundary of the optimal or stable volume.

```python
def boundary_points(self):
    """
    Returns:
        list[list[float]]: All vertices in the boundary of the optimal/stable volume
    """
    return self.boundary_vertices()
```

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

### Create Persistence Diagram

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Methods to instantiate persistence diagrams from scratch or from birth-death lists.

```APIDOC
## POST /pd/create

### Description
Creates a new persistence diagram object.

### Parameters
#### Request Body
- **degree** (int) - Required - The degree of the diagram.
- **births** (numpy.ndarray) - Required - List of birth times.
- **deaths** (numpy.ndarray) - Required - List of death times.
- **ess_births** (numpy.ndarray) - Optional - Birth times of essential pairs.
- **sign_flipped** (bool) - Optional - Whether the sign is flipped.

### Response
#### Success Response (200)
- **pd** (PD) - A PD object.
```

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

### Get Stable Volume Pixels

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/bitmap_phtrees.html

Retrieves the coordinates of all pixels belonging to the stable volume.

```APIDOC
## GET /websites/homcloud_dev/volume

### Description
Returns the pixels of the stable volume.

### Method
GET

### Endpoint
/websites/homcloud_dev/volume

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **volume** (list[tuple[int,...]]) - The coordinates of all pixels.

#### Response Example
{
  "volume": [
    [0, 0, 0],
    [1, 1, 1]
  ]
}
```

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

### Get Death Time of Optimal 1-Cycle

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/bitmap_optimal_1_cycle.html

Returns the death time of the optimal 1-cycle.

```python
def death_time(self):
        """
        Returns:
            float: The death time.
        """
        return self.orig.death_time
```

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

### Import libraries

Source: https://homcloud.dev/py-tutorial/grayscale_image_en.html

Load numpy and matplotlib for data handling and visualization.

```python
import numpy as np  # numpy ライブラリの読み込み
import matplotlib.pyplot as plt  #  可視化のため matplitlib の読み込み
```

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

### Get Birth Time of Optimal 1-Cycle

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/bitmap_optimal_1_cycle.html

Returns the birth time of the optimal 1-cycle.

```python
def birth_time(self):
        """
        Returns:
            float: The birth time.
        """
        return self.orig.birth_time
```

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

### Load XYZ file with ASE

Source: https://homcloud.dev/py-tutorial/analysis_of_atomic_configurations_2_en.html

Reads the converted XYZ file into an ASE Atoms object.

```python
sio2 = ase.io.read("sio2-cart.xyz")
```

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

### Create and Navigate to HomCloud Directory

Source: https://homcloud.dev/install-guide/install_guide_for_Ubuntu_venv.en.html

Creates a new directory named 'homcloud' and changes the current directory to it. This directory will serve as the workspace for the virtual environment.

```bash
mkdir homcloud
cd homcloud
```

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

### Get All Nodes

Source: https://homcloud.dev/python-api/interface.html

Returns a list of all nodes present in the PHTrees structure. This is a property of the PHTrees module.

```python
property all_nodes#
    
Return all nodes. 

Returns:
    
The nodes. 

Return type:
    
list[`PHTrees.Node`]
```

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

### Get Specific Birth-Death Pair

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/pd.html

Retrieves a specific birth-death pair from the Persistence Diagram by its index.

```python
return Pair(self, nth)
```

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

### Load PHTrees from PDList

Source: https://homcloud.dev/python-api/interface.html

Shows how to compute and load PHTrees from an alpha filtration for optimal volume analysis.

```python
>>> import homcloud.interface as hc
>>> pointcloud = hc.example_data("tetrahedron")
>>> # Compute PDs and PHTrees
>>> pdlist = hc.PDList.from_alpha_filtration(pointcloud, save_boundary_map=True, save_phtrees=True)
>>> # Load phtrees
>>> phtrees = pdlist.dth_diagram(2).load_phtrees()
>>> # Query the node whose birth-death pair is nearest to (19, 21).
```

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

### Get Points Symbols

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/phtrees.html

Returns the symbolic representation of all vertices within the optimal or stable volume.

```python
def points_symbols(self):
    """
    Returns:
        list[str]: All vertices in the optimal/stable volume
        in the form of the symbolic representation.
    """
    return self.vertices("symbols")
```

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

### Visualize persistence diagrams

Source: https://homcloud.dev/py-tutorial/grayscale_image_en.html

Load and plot the persistence diagrams with adjustable resolution.

```python
pd = hc.PDList("grayscale.pdgm").dth_diagram(0)
```

```python
pd.histogram().plot(colorbar={"type": "log"})
```

```python
pd.histogram(x_bins=64).plot(colorbar={"type": "log"})
```

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

### GET /bitmap_phtrees/nearest_pair_node

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/bitmap_phtrees.html

Searches for a tree node corresponding to the birth-death pair nearest to the specified coordinates.

```APIDOC
## GET /bitmap_phtrees/nearest_pair_node

### Description
Searches a tree node corresponding the birth-death pair nearest to (x, y).

### Parameters
#### Query Parameters
- **x** (float) - Required - The x-coordinate.
- **y** (float) - Required - The y-coordinate.

### Response
#### Success Response (200)
- **Node** (object) - The found tree node.
```

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

### Get Degree of Persistent Homology

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/bitmap_phtrees.html

Returns the degree of the persistent homology computed from the bitmap filtration.

```python
return self.treedict["degree"]
```

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

### Load 1D PD from file

Source: https://homcloud.dev/py-tutorial/analysis_of_atomic_configurations_2_en.html

Loads a 1-dimensional persistence diagram from a specified file. Ensure the file exists and is in the correct format.

```python
pd1 = hc.PDList("sio2.pdgm").dth_diagram(1)
```

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

### Get Birth Position of Optimal 1-Cycle

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/bitmap_optimal_1_cycle.html

Returns the coordinate of the birth position for the optimal 1-cycle.

```python
def birth_position(self):
        """
        Returns:
            tuple of float*N: The coordinate of birth position. (N: dimension)
        """
        return self.orig.path[0]
```

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

### Visualize 3D structure

Source: https://homcloud.dev/py-tutorial/analysis_of_atomic_configurations_2_en.html

Initializes a 3D viewer and adds a molecular model from XYZ data. Sets the display style for sticks with a default color scheme and opacity.

```python
view = py3Dmol.view()
view.addModel(sio2_xyz, "xyz")
# Display the bonds as semi-transparent
view.setStyle({'stick': {"colorscheme": "default", "opacity": 0.8}})
```

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

### Get Atom Positions

Source: https://homcloud.dev/py-tutorial/analysis_of_atomic_configurations_1_en.html

Retrieve the coordinates of atoms from an ASE `Atoms` object using `get_positions()`.

```python
triangle_atoms.get_positions()
```

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

### Test HomCloud Docker Image

Source: https://homcloud.dev/install-guide/install_guide_for_Docker.en.html

Runs the self-check module to verify the installation and dependencies within the container.

```bash
docker run -it ohai9/homcloud:4.4.1-python3.12.2-slim-bookworm  /usr/local/bin/python3 -m homcloud.self_check
```

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

### Get Volume Points

Source: https://homcloud.dev/python-api/interface.html

Returns the points that define the optimal volume. This method is part of the Volume class.

```python
points()[source]#
     

Returns:
    
Points in the optimal volume. 

Return type:
    
list[list[float]], a.k.a list[Point] 
```

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

### Optimal1Cycle Class Methods

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/boundary_map_optimal_1_cycle.html

Methods for retrieving properties and visualization objects for an optimal 1-cycle.

```APIDOC
## Optimal1Cycle Methods

### birth_time()
Returns the birth time of the pair.
- **Returns**: float

### death_time()
Returns the death time of the pair.
- **Returns**: float

### path(by="default")
Returns all edges in the optimal 1-cycle.
- **Parameters**: by (string) - Optional - Geometry resolver type
- **Returns**: list of cell

### boundary_points(by="default")
Returns all vertices in the optimal 1-cycle.
- **Parameters**: by (string) - Optional - Geometry resolver type
- **Returns**: list of point

### to_plotly3d_trace(color=None, width=1, name="")
Constructs a plotly's trace object to visualize the optimal 1-cycle.
- **Parameters**:
  - color (string) - Optional
  - width (int) - Optional
  - name (string) - Optional
- **Returns**: plotly.graph_objects.Scatter3d

### to_pyvista_mesh()
Constructs a PyVista's mesh object to visualize the optimal 1-cycle.
- **Returns**: pyvista.PolyData
```

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

### Visualize Optimal Volume with Periodic Boundary Adjustment

Source: https://homcloud.dev/py-tutorial/pointcloud_pbc_en.html

Visualize the optimal volume while adjusting for periodic boundaries. A red wireframe box indicates the periodic boundary limits.

```python
pl = pv.Plotter()
pl.add_mesh(optimal_volume.to_pyvista_boundary_mesh(adjust_periodic_boundary=(0.3, None)))
pl.add_mesh(pv.Box(bounds=(0, 1, 0, 1, 0, 1), level=2), style='wireframe', color="red")  # (0, 1, 0, 1, 0, 1) means periodic boundary box.
pl.show()
```

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

### Get Volume Death Simplex

Source: https://homcloud.dev/python-api/interface.html

Returns the death simplex of the volume. This method is part of the Volume class.

```python
death_simplex()#
    
Returns the death simplex. 
```

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

### Get Volume Birth Simplex

Source: https://homcloud.dev/python-api/interface.html

Returns the birth simplex of the volume. This method is part of the Volume class.

```python
birth_simplex()#
    
Returns the birth simplex. 
```

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

### Initialize BitmapOptimal1Cycle

Source: https://homcloud.dev/python-api/_modules/homcloud/interface/bitmap_optimal_1_cycle.html

Initializes the BitmapOptimal1Cycle with an original object.

```python
def __init__(self, orig):
        self.orig = orig
```

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

### Get Volume Simplices

Source: https://homcloud.dev/python-api/interface.html

Returns the simplices that constitute the optimal volume. This method is part of the Volume class.

```python
simplices()#
     

Returns:
    
The simplices in the optimal volume. 

Return type:
    
list[list[list[float]]], a.k.a list[Simplex] 
```
Tokens:
Raw