unike 3.0.1__py3-none-any.whl

unike/module/BaseModule.py

@@ -0,0 +1,130 @@
+# coding:utf-8
+#
+# unike/module/BaseModule.py
+# 
+# git pull from OpenKE-PyTorch by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on May 7, 2023
+# updated by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on Jan 4, 2023
+# 
+# 该头文件定义了 BaseModule.
+
+"""BaseModule - 所有模块的基类"""
+
+import os
+import json
+import torch
+import torch.nn as nn
+import numpy as np
+from typing import Any
+
+class BaseModule(nn.Module):
+
+	"""继承自 :py:class:`torch.nn.Module`，并且封装了一些常用功能，如加载和保存模型。"""
+
+	def __init__(self):
+
+		"""创建 BaseModule 对象。"""
+
+		super(BaseModule, self).__init__()
+
+		#: 常数 0
+		self.zero_const: torch.nn.parameter.Parameter = nn.Parameter(torch.Tensor([0]))
+		self.zero_const.requires_grad = False
+
+		#: 常数 pi
+		self.pi_const: torch.nn.parameter.Parameter = nn.Parameter(torch.Tensor([3.14159265358979323846]))
+		self.pi_const.requires_grad = False
+
+	def load_checkpoint(self, path: str):
+		
+		"""加载模型权重。
+
+		:param path: 模型保存的路径
+		:type path: str
+		"""
+
+		self.load_state_dict(torch.load(os.path.join(path)))
+		self.eval()
+
+	def save_checkpoint(self, path: str):
+
+		"""保存模型权重。
+
+		:param path: 模型保存的路径
+		:type path: str
+		"""
+
+		if not os.path.exists(os.path.split(path)[0]):
+			os.makedirs(os.path.split(path)[0], exist_ok=True)
+		torch.save(self.state_dict(), path)
+
+	def get_parameters(
+		self,
+		mode: str = "numpy",
+		param_dict: dict[str, Any] | None = None
+		) -> dict[str, np.ndarray] | dict[str, list] | dict[str, torch.Tensor]:
+
+		"""获得模型权重。
+
+		:param mode: 模型保存的格式，可以选择 ``numpy`` 、 ``list`` 和 ``Tensor`` 。
+		:type path: str
+		:param param_dict: 可以选择从哪里获得模型权重。
+		:type param_dict: dict[str, typing.Any] | None
+		:returns: 模型权重字典。
+		:rtype: dict[str, numpy.ndarray] | dict[str, list] | dict[str, torch.Tensor]
+		"""
+
+		all_param_dict = self.state_dict()
+		if param_dict == None:
+			param_dict = all_param_dict.keys()
+		res = {}
+		for param in param_dict:
+			if mode == "numpy":
+				res[param] = all_param_dict[param].cpu().numpy()
+			elif mode == "list":
+				res[param] = all_param_dict[param].cpu().numpy().tolist()
+			else:
+				res[param] = all_param_dict[param]
+		return res
+
+	def set_parameters(self, parameters: dict[str, Any]):
+		
+		"""加载模型权重。
+
+		:param parameters: 模型权重字典。
+		:type parameters: dict[str, typing.Any]
+		"""
+
+		for i in parameters:
+			parameters[i] = torch.Tensor(parameters[i])
+		self.load_state_dict(parameters, strict = False)
+		self.eval()
+
+	def load_parameters(self, path: str):
+
+		"""加载模型权重。
+
+		:param path: 模型保存的路径
+		:type path: str
+		"""
+
+		f = open(path, "r")
+		parameters = json.loads(f.read())
+		f.close()
+		for i in parameters:
+			parameters[i] = torch.Tensor(parameters[i])
+		self.load_state_dict(parameters, strict = False)
+		self.eval()
+
+	def save_parameters(self, path: str):
+
+		"""用 json 格式保存模型权重。
+
+		:param path: 模型保存的路径
+		:type path: str
+		"""
+
+		if not os.path.exists(os.path.split(path)[0]):
+			os.makedirs(os.path.split(path)[0], exist_ok=True)
+		f = open(path, "w")
+		f.write(json.dumps(self.get_parameters("list")))
+		f.close()

unike/module/__init__.py

@@ -0,0 +1,20 @@
+# coding:utf-8
+#
+# unike/module/__init__.py
+# 
+# git pull from OpenKE-PyTorch by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on May 7, 2023
+# updated by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on May 28, 2023
+# 
+# 该头文件定义了 module 接口.
+
+"""模块部分，包含模型和损失函数。"""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+from .BaseModule import BaseModule
+
+__init__ = {
+	'BaseModule'
+}

unike/module/loss/CompGCNLoss.py

@@ -0,0 +1,96 @@
+# coding:utf-8
+#
+# unike/module/loss/CompGCNLoss.py
+#
+# created by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on Jan 19, 2024
+# updated by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on May 23, 2024
+#
+# 该脚本定义了 CompGCNLoss 类.
+
+"""
+CompGCNLoss - 损失函数类，CompGCN 原论文中应用这种损失函数完成模型学习。
+"""
+
+import torch
+from .Loss import Loss
+from typing import Any
+from ..model import CompGCN
+
+class CompGCNLoss(Loss):
+    
+    """
+    ``CompGCN`` :cite:`CompGCN` 原论文中应用这种损失函数完成模型训练。
+    
+    .. Note:: :py:meth:`forward` 中的正样本评分函数的得分应大于负样本评分函数的得分。
+    
+    例子::
+
+        from unike.module.loss import CompGCNLoss
+        from unike.module.strategy import CompGCNSampling
+
+        # define the loss function
+        model = CompGCNSampling(
+            model = compgcn,
+            loss = CompGCNLoss(model = compgcn),
+            ent_tol = dataloader.get_ent_tol()
+        )
+    """
+
+    def __init__(
+        self,
+        model: CompGCN):
+
+        """创建 CompGCNLoss 对象。
+        
+        :param model: 模型
+        :type model: CompGCN
+		"""
+
+        super(CompGCNLoss, self).__init__()
+
+        #: 模型
+        self.model: CompGCN = model
+        #: 损失函数
+        self.loss: torch.nn.BCELoss = torch.nn.BCELoss()
+
+    def forward(
+        self,
+        pred: torch.Tensor,
+        label: torch.Tensor) -> torch.Tensor:
+
+        """计算 CompGCNLoss 损失函数。定义每次调用时执行的计算。:py:class:`torch.nn.Module` 子类必须重写 :py:meth:`torch.nn.Module.forward`。
+        
+        :param pred: 模型的得分。
+        :type pred: torch.Tensor
+        :param labels: 标签
+        :type labels: torch.Tensor
+        :returns: 损失值
+        :rtype: torch.Tensor
+		"""
+        
+        loss = self.loss(pred, label)
+        return loss
+
+def get_compgcn_loss_hpo_config() -> dict[str, dict[str, Any]]:
+
+	"""返回 :py:class:`CompGCNLoss` 的默认超参数优化配置。
+	
+	默认配置为::
+	
+	    parameters_dict = {
+	    	'loss': {
+	    		'value': 'CompGCNLoss'
+	    	}
+	    }
+	
+	:returns: :py:class:`CompGCNLoss` 的默认超参数优化配置
+	:rtype: dict[str, dict[str, typing.Any]]
+	"""
+
+	parameters_dict = {
+		'loss': {
+			'value': 'CompGCNLoss'
+		}
+	}
+		
+	return parameters_dict

unike/module/loss/Loss.py

@@ -0,0 +1,26 @@
+# coding:utf-8
+#
+# unike/module/loss/Loss.py
+#
+# git pull from OpenKE-PyTorch by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on May 7, 2023
+# updated by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on Jan 4, 2023
+#
+# 该脚本定义了损失函数的基类.
+
+"""
+Loss - 该脚本定义了损失函数的基类。
+"""
+
+from ..BaseModule import BaseModule
+
+class Loss(BaseModule):
+
+	"""
+	继承自 :py:class:`unike.module.BaseModule`，什么额外的属性都没有增加。
+	"""
+
+	def __init__(self):
+		
+		"""创建 Loss 对象。"""
+
+		super(Loss, self).__init__()

unike/module/loss/MarginLoss.py

@@ -0,0 +1,148 @@
+# coding:utf-8
+#
+# unike/module/loss/MarginLoss.py
+#
+# git pull from OpenKE-PyTorch by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on May 7, 2023
+# updated by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on May 9, 2024
+#
+# 该脚本定义了 margin-based ranking criterion 损失函数.
+
+"""
+MarginLoss - 损失函数类，TransE 原论文中应用这种损失函数完成模型学习。
+"""
+
+import torch
+import numpy as np
+from typing import Any
+import torch.nn as nn
+import torch.nn.functional as F
+from .Loss import Loss
+
+class MarginLoss(Loss):
+
+	"""
+	``TransE`` :cite:`TransE` 原论文中应用这种损失函数完成模型训练。
+	
+	.. Note:: :py:meth:`forward` 中的正样本评分函数的得分应小于负样本评分函数的得分。
+
+	例子::
+
+		from unike.module.model import TransE
+		from unike.module.loss import MarginLoss
+		from unike.module.strategy import NegativeSampling
+		
+		# define the model
+		transe = TransE(
+			ent_tol = dataloader.get_ent_tol(),
+			rel_tol = dataloader.get_rel_tol(),
+			dim = 50, 
+			p_norm = 1, 
+			norm_flag = True
+		)
+		
+		# define the loss function
+		model = NegativeSampling(
+			model = transe, 
+			loss = MarginLoss(margin = 1.0),
+			regul_rate = 0.01
+		)
+	"""
+
+	def __init__(
+		self,
+		adv_temperature: float | None = None,
+		margin: float = 6.0):
+
+		"""创建 MarginLoss 对象。
+
+		:param adv_temperature: RotatE 提出的自我对抗负采样中的温度。
+		:type adv_temperature: float
+		:param margin: gamma。
+		:type margin: float
+		"""
+
+		super(MarginLoss, self).__init__()
+
+		#: gamma
+		self.margin: torch.nn.parameter.Parameter = nn.Parameter(torch.Tensor([margin]))
+		self.margin.requires_grad = False
+		if adv_temperature != None:
+			#: RotatE 提出的自我对抗负采样中的温度。
+			self.adv_temperature: torch.nn.parameter.Parameter = nn.Parameter(torch.Tensor([adv_temperature]))
+			self.adv_temperature.requires_grad = False
+			#: 是否启用 RotatE 提出的自我对抗负采样。
+			self.adv_flag: bool = True
+		else:
+			self.adv_flag: bool = False
+	
+	def get_weights(
+		self,
+		n_score: torch.Tensor) -> torch.Tensor:
+
+		"""计算 RotatE 提出的自我对抗负采样中的负样本的分布概率。
+		
+		:param n_score: 负样本评分函数的得分。
+		:type n_score: torch.Tensor
+		:returns: 自我对抗负采样中的负样本的分布概率
+		:rtype: torch.Tensor
+		"""	
+
+		return F.softmax(-n_score * self.adv_temperature, dim = -1).detach()
+
+	def forward(
+		self,
+		p_score: torch.Tensor,
+		n_score: torch.Tensor) -> torch.Tensor:
+		
+		"""计算 margin-based ranking criterion 损失函数。定义每次调用时执行的计算。
+		:py:class:`torch.nn.Module` 子类必须重写 :py:meth:`torch.nn.Module.forward`。
+		
+		:param p_score: 正样本评分函数的得分。
+		:type p_score: torch.Tensor
+		:param n_score: 负样本评分函数的得分。
+		:type n_score: torch.Tensor
+		:returns: 损失值
+		:rtype: torch.Tensor
+		"""
+
+		if self.adv_flag:
+			return (self.get_weights(n_score) * torch.max(p_score - n_score,
+						 -self.margin)).sum(dim = -1).mean() + self.margin
+		else:
+			return (torch.max(p_score - n_score, -self.margin)).mean() + self.margin
+
+def get_margin_loss_hpo_config() -> dict[str, dict[str, Any]]:
+
+	"""返回 :py:class:`MarginLoss` 的默认超参数优化配置。
+	
+	默认配置为::
+	
+		parameters_dict = {
+			'loss': {
+				'value': 'MarginLoss'
+			},
+			'adv_temperature': {
+				'values': [1.0, 3.0, 6.0]
+			},
+			'margin': {
+				'values': [1.0, 3.0, 6.0]
+			}
+		}
+	
+	:returns: :py:class:`MarginLoss` 的默认超参数优化配置
+	:rtype: dict[str, dict[str, typing.Any]]
+	"""
+
+	parameters_dict = {
+		'loss': {
+			'value': 'MarginLoss'
+		},
+		'adv_temperature': {
+			'values': [1.0, 3.0, 6.0]
+		},
+		'margin': {
+			'values': [1.0, 3.0, 6.0]
+		}
+	}
+		
+	return parameters_dict

unike/module/loss/RGCNLoss.py

@@ -0,0 +1,117 @@
+# coding:utf-8
+#
+# unike/module/loss/RGCN_Loss.py
+#
+# created by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on Jan 16, 2023
+# updated by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on Jan 17, 2023
+#
+# 该脚本定义了 RGCNLoss 类.
+
+"""
+RGCNLoss - 损失函数类，R-GCN 原论文中应用这种损失函数完成模型学习。
+"""
+
+import torch
+from typing import Any
+from ..model import RGCN
+import torch.nn.functional as F
+from .Loss import Loss
+
+class RGCNLoss(Loss):
+    
+    """
+	``R-GCN`` :cite:`R-GCN` 原论文中应用这种损失函数完成模型训练。
+	
+	.. Note:: :py:meth:`forward` 中的正样本评分函数的得分应大于负样本评分函数的得分。
+
+	例子::
+
+        from unike.module.loss import RGCNLoss
+        from unike.module.strategy import RGCNSampling
+                
+        # define the loss function
+        model = RGCNSampling(
+        	model = rgcn,
+        	loss = RGCNLoss(model = rgcn, regularization = 1e-5)
+        )
+	"""
+
+    def __init__(
+        self,
+        model: RGCN,
+        regularization: float):
+
+        """创建 RGCNLoss 对象。
+        
+        :param model: 模型
+        :type model: RGCN
+        :param regularization: 正则率
+        :type regularization: float
+		"""
+        
+        super(RGCNLoss, self).__init__()
+
+        #: 模型
+        self.model: RGCN = model
+        #: 正则率
+        self.regularization: float = regularization
+    
+    def reg_loss(self) -> torch.Tensor:
+
+        """获得正则部分的损失。
+        
+        :returns: 损失值
+        :rtype: torch.Tensor
+		"""
+
+        return torch.mean(self.model.Loss_emb.pow(2)) + torch.mean(self.model.rel_emb.pow(2))
+
+    def forward(
+        self,
+        score: torch.Tensor,
+        labels: torch.Tensor) -> torch.Tensor:
+
+        """计算 RGCNLoss 损失函数。定义每次调用时执行的计算。:py:class:`torch.nn.Module` 子类必须重写 :py:meth:`torch.nn.Module.forward`。
+        
+        :param score: 模型的得分。
+        :type score: torch.Tensor
+        :param labels: 标签
+        :type labels: torch.Tensor
+        :returns: 损失值
+        :rtype: torch.Tensor
+		"""
+
+        loss = F.binary_cross_entropy_with_logits(score, labels)
+        regu = self.regularization * self.reg_loss()
+        loss += regu
+        return loss
+
+def get_rgcn_loss_hpo_config() -> dict[str, dict[str, Any]]:
+
+	"""返回 :py:class:`RGCNLoss` 的默认超参数优化配置。
+	
+	默认配置为::
+	
+	    parameters_dict = {
+	    	'loss': {
+	    		'value': 'RGCNLoss'
+	    	},
+	    	'regularization': {
+	    		'value': 1e-5
+	    	}
+	    }
+	
+	:returns: :py:class:`RGCNLoss` 的默认超参数优化配置
+	:rtype: dict[str, dict[str, typing.Any]]
+	"""
+
+	parameters_dict = {
+		'loss': {
+			'value': 'RGCNLoss'
+		},
+		'regularization': {
+			'value': 1e-5
+		}
+	}
+		
+	return parameters_dict

unike/module/loss/SigmoidLoss.py

@@ -0,0 +1,145 @@
+# coding:utf-8
+#
+# unike/module/loss/SigmoidLoss.py
+#
+# git pull from OpenKE-PyTorch by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on May 7, 2023
+# updated by LuYF-Lemon-love <luyanfeng_nlp@qq.com> on Jan 11, 2023
+#
+# 该脚本定义了 regularized logistic loss 损失函数.
+
+"""
+SigmoidLoss - 损失函数类，RotatE 原论文应用这种损失函数完成模型学习。
+"""
+
+import torch
+import numpy as np
+import torch.nn as nn
+from typing import Any
+import torch.nn.functional as F
+from .Loss import Loss
+
+class SigmoidLoss(Loss):
+	
+	"""
+	``RotatE`` :cite:`RotatE` 原论文中应用这种损失函数完成模型训练。
+	
+	.. Note:: :py:meth:`forward` 中的正样本评分函数的得分应大于负样本评分函数的得分。
+
+	例子::
+
+		from unike.module.loss import SigmoidLoss
+		from unike.module.strategy import NegativeSampling
+
+		# define the loss function
+		model = NegativeSampling(
+			model = rotate, 
+			loss = SigmoidLoss(adv_temperature = 2),
+			batch_size = train_dataloader.get_batch_size(), 
+			regul_rate = 0.0
+		)
+	"""
+
+	def __init__(
+		self,
+		adv_temperature: float | None = None):
+
+		"""创建 SigmoidLoss 对象。
+
+		:param adv_temperature: RotatE 提出的自我对抗负采样中的温度。
+		:type adv_temperature: float
+		"""
+
+		super(SigmoidLoss, self).__init__()
+		#: 逻辑函数，类型为 :py:class:`torch.nn.LogSigmoid`。
+		self.criterion: torch.nn.LogSigmoid = nn.LogSigmoid()
+		if adv_temperature != None:
+			#: RotatE 提出的自我对抗负采样中的温度。
+			self.adv_temperature: torch.nn.parameter.Parameter = nn.Parameter(torch.Tensor([adv_temperature]))
+			self.adv_temperature.requires_grad = False
+			#: 是否启用 RotatE 提出的自我对抗负采样。
+			self.adv_flag: bool = True
+		else:
+			self.adv_flag: bool = False
+
+	def get_weights(
+		self,
+		n_score: torch.Tensor) -> torch.Tensor:
+
+		"""计算 RotatE 提出的自我对抗负采样中的负样本的分布概率。
+		
+		:param n_score: 负样本评分函数的得分。
+		:type n_score: torch.Tensor
+		:returns: 自我对抗负采样中的负样本的分布概率
+		:rtype: torch.Tensor
+		"""
+
+		return F.softmax(n_score * self.adv_temperature, dim = -1).detach()
+
+	def forward(
+		self,
+		p_score: torch.Tensor,
+		n_score: torch.Tensor) -> torch.Tensor:
+
+		"""计算 SigmoidLoss 损失函数。定义每次调用时执行的计算。
+		:py:class:`torch.nn.Module` 子类必须重写 :py:meth:`torch.nn.Module.forward`。
+		
+		:param p_score: 正样本评分函数的得分。
+		:type p_score: torch.Tensor
+		:param n_score: 负样本评分函数的得分。
+		:type n_score: torch.Tensor
+		:returns: 损失值
+		:rtype: torch.Tensor
+		"""
+
+		if self.adv_flag:
+			return -(self.criterion(p_score).mean() + (self.get_weights(n_score) * self.criterion(-n_score)).sum(dim = -1).mean()) / 2
+		else:
+			return -(self.criterion(p_score).mean() + self.criterion(-n_score).mean()) / 2
+
+	def predict(
+		self,
+		p_score: torch.Tensor,
+		n_score: torch.Tensor) -> np.ndarray:
+
+		"""SigmoidLoss 的推理方法。
+		
+		:param p_score: 正样本评分函数的得分。
+		:type p_score: torch.Tensor
+		:param n_score: 负样本评分函数的得分。
+		:type n_score: torch.Tensor
+		:returns: 损失值
+		:rtype: numpy.ndarray
+		"""
+
+		score = self.forward(p_score, n_score)
+		return score.cpu().data.numpy()
+
+def get_sigmoid_loss_hpo_config() -> dict[str, dict[str, Any]]:
+
+	"""返回 :py:class:`SigmoidLoss` 的默认超参数优化配置。
+	
+	默认配置为::
+	
+		parameters_dict = {
+			'loss': {
+				'value': 'SigmoidLoss'
+			},
+			'adv_temperature': {
+				'values': [1.0, 3.0, 6.0]
+			}
+		}
+	
+	:returns: :py:class:`SigmoidLoss` 的默认超参数优化配置
+	:rtype: dict[str, dict[str, typing.Any]]
+	"""
+
+	parameters_dict = {
+		'loss': {
+			'value': 'SigmoidLoss'
+		},
+		'adv_temperature': {
+			'values': [1.0, 3.0, 6.0]
+		}
+	}
+		
+	return parameters_dict