From 8eed7950f890564ced8696ab06644c38432f4e7b Mon Sep 17 00:00:00 2001
From: Pauli Virtanen <pauli.t.virtanen@jyu.fi>
Date: Tue, 23 Apr 2024 16:25:33 +0300
Subject: [PATCH] Documentation
---
doc/api.rst | 7 ++++++-
usadelndsoc/__init__.py | 5 +++++
usadelndsoc/bcs.py | 14 ++++++++++++++
usadelndsoc/plotting.py | 25 +++++++++++++++++++++++++
usadelndsoc/solver.py | 25 +++++++++++++++++++++++++
usadelndsoc/util.py | 22 ++++++++++++++++++++++
6 files changed, 97 insertions(+), 1 deletion(-)
diff --git a/doc/api.rst b/doc/api.rst
index 19f4e14..85c89e3 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -16,11 +16,16 @@ API
:members:
:undoc-members:
+.. autofunction:: usadelndsoc.bcs.BCS_Delta
+
.. automodule:: usadelndsoc
:members:
:undoc-members:
.. py:data:: usadelndsoc.logger
- `logging.Logger` instance used.
+ `logging` instance used.
+.. automodule:: usadelndsoc.plotting
+ :members:
+ :undoc-members:
diff --git a/usadelndsoc/__init__.py b/usadelndsoc/__init__.py
index de55f55..1459a04 100644
--- a/usadelndsoc/__init__.py
+++ b/usadelndsoc/__init__.py
@@ -37,6 +37,11 @@ def _init_logging():
class with_log_level(contextlib.ContextDecorator):
+ """
+ Context decorator that temporarily changes
+ the log level of `usadelndsoc.logger`.
+ """
+
def __init__(self, level):
self._level = level
diff --git a/usadelndsoc/bcs.py b/usadelndsoc/bcs.py
index c3d4ffb..2410563 100644
--- a/usadelndsoc/bcs.py
+++ b/usadelndsoc/bcs.py
@@ -18,6 +18,20 @@ __all__ = ["BCS_Delta"]
def BCS_Delta(T, Tc, h=0):
"""
Evaluate Delta in a bulk BCS superconductor.
+
+ Parameters
+ ----------
+ T : float
+ Temperature
+ Tc : float
+ BCS critical temperature
+ h : float
+ Exchange field
+
+ Returns
+ -------
+ Delta : float
+ Order parameter
"""
Delta_0 = pi / exp(euler_gamma) * Tc
diff --git a/usadelndsoc/plotting.py b/usadelndsoc/plotting.py
index 93bf6b7..e8e3e72 100644
--- a/usadelndsoc/plotting.py
+++ b/usadelndsoc/plotting.py
@@ -17,6 +17,9 @@ __all__ = [
def plot_Delta_J_2d(x, y, Delta, J, ax=None):
+ """
+ Color plot of order parameter and supercurrents.
+ """
if ax is None:
ax = plt.gca()
@@ -40,6 +43,10 @@ def plot_Delta_J_2d(x, y, Delta, J, ax=None):
class ComplexColorMesh:
+ """
+ Object representing Matplotlib complex colormap.
+ """
+
def __init__(self, phase, amplitude):
self.phase = phase
self.amplitude = amplitude
@@ -62,6 +69,22 @@ class ComplexColorMesh:
def pcolormesh_complex(x, y, data, ax=None):
+ """
+ Plot complex-valued function as a color map.
+
+ Lightness indicates amplitude, color indicates phase angle.
+
+ Parameters
+ ----------
+ x : array of float, shape (nx,)
+ y : array of float, shape (ny,)
+ data : array of complex, shape (nx, ny)
+ ax : matplotlib axis
+
+ Returns
+ -------
+ cmesh : ComplexColorMesh
+ """
nx = data.shape[0]
ny = data.shape[1]
dx = np.median(np.diff(x))
@@ -98,6 +121,7 @@ def pcolormesh_complex(x, y, data, ax=None):
@functools.lru_cache()
def cmap_hue_cyclic():
+ """Cyclic hue Matplotlib color map"""
from ._plotting_data import data
return _get_cmap(data)
@@ -105,6 +129,7 @@ def cmap_hue_cyclic():
@functools.lru_cache()
def cmap_huegray_r():
+ """Reverse grayscale colormap, corresponding to cmap_hue_cyclic()"""
from ._plotting_data import data_l
return _get_cmap(np.c_[data_l, data_l, data_l][::-1])
diff --git a/usadelndsoc/solver.py b/usadelndsoc/solver.py
index 2da894a..8688330 100644
--- a/usadelndsoc/solver.py
+++ b/usadelndsoc/solver.py
@@ -1200,6 +1200,31 @@ def cpr(
filename=None,
**selfcons_kw,
):
+ """
+ Compute current-phase relation with selfconsistency.
+
+ Adjust superconducting phases in cells indicated by `phase_mask`.
+
+ Parameters
+ ----------
+ solve : Solver
+ Solver instance to use
+ T : float
+ Temperature
+ T_c0 : array of float
+ Critical temperature
+ phase_mask : array of bool
+ Cells where to tune superconducting phase
+ max_points : int
+ ds : float
+ Step size
+ phi0 : float
+ filename : str, optional
+ File to resume or save progress. Computation is resumed if
+ the file exists and parameter values in it match.
+ **selfcons_kw
+ Parameters passed on to `Solver.self_consistency`.
+ """
nx, ny = solver.shape
phase_mask = phase_mask.astype(bool)
diff --git a/usadelndsoc/util.py b/usadelndsoc/util.py
index 15766c1..f256b08 100644
--- a/usadelndsoc/util.py
+++ b/usadelndsoc/util.py
@@ -83,6 +83,28 @@ def vectorize_parallel(
excluded=None,
noarray=False,
):
+ """
+ Decorator to vectorize and function to evaluate elements in parallel.
+ Uses *joblib* for parallelization.
+
+ Parameters
+ ----------
+ func : function
+ backend : str
+ Joblib backend
+ n_jobs : int
+ Number of jobs, -1 means number of CPUs.
+ returns_object : bool
+ Put function return values to an object array.
+ batch_size : {"auto", int}
+ included : tuple
+ Function argument names to include in vectorization.
+ excluded : tuple
+ Function argument names to exclude from vectorization.
+ noarray : bool
+ Convert array-valued return values to scalars.
+ """
+
if func is None:
def deco(func):
--
GitLab