Coverage for gpaw/coding_style.py: 38%

1# Copyright (C) 2008 CAMd 

2# Please see the accompanying LICENSE file for further information. 

3 

4"""This module is an example of good coding style. 

5 

6This docstring should begin with a one-line description followed by a 

7blank line, and then this paragraph describing in more word what kind 

8of functionality this module implements. 

9 

10After this docstring we have import statements in this order: 

11 

121. From the Python standard library. 

132. Other libraries (numpy, ase, ...). 

143. GPAW stuff. 

15""" 

16 

17from math import pi 

18 

19import numpy as np 

20from ase.units import Ha 

21 

22from gpaw import debug 

23import gpaw.mpi as mpi 

24 

25 

26class SimpleExample: 

27 """A simple example class. 

28 

29 A headline, a blank line and then this longer description of the 

30 class. 

31 

32 Here one could put an example of how to use the class:: 

33 

34 ex = SimpleExample('Test', (2, 3), int, verbose=False) 

35 ex.run(7, verbose=True) 

36 

37 """ 

38 

39 def __init__(self, name, shape, dtype=float, verbose=True): 

40 """Create an example object. 

41 

42 Again, headline, blank line, ... . If there are many 

43 parameters, there should be a parameter section (see below). 

44 If there only a few possible arguments, then the parameter 

45 section can be left out and the arguments can be described in 

46 the section following the headline and blank line (see the 

47 `run` method). If a method is real simple and 

48 self-explanatory, the docstring can be the headline only (see 

49 the `reset` method). 

50 

51 Parameters: 

52 

53 name : string 

54 Name of the example. 

55 shape: tuple 

56 Shape of the ndarray. 

57 dtype: ndarray datatype 

58 The datatype of the ndarray. Here, the description can go 

59 on to a second line if needed. Make sure that the 

60 indentation is like shown here, and remember to end with a 

61 period. 

62 verbose: boolean 

63 Print information about this and that. 

64 

65 Other sections: 

66 

67 There can be other sections - see bolow and here: 

68 

69 https://scipy.org/... 

70 

71 """ 

72 

73 self.name = name 

74 if verbose: 

75 print(name) 

76 self.a = np.zeros(shape, dtype) 

77 self.verbose = verbose 

78 

79 def method_with_long_name(self, b, out=None): 

80 """Do something very complicated. 

81 

82 Long story with all details here ... 

83 

84 Parameters: 

85 

86 b: ndarray 

87 Add this array. 

88 out: ndarray 

89 Optional output array. 

90 

91 Returns: 

92 

93 The sum of ... 

94 """ 

95 

96 if out is None: 

97 return self.a + b 

98 else: 

99 return np.add(self.a, b, out) 

100 

101 def run(self, n): 

102 """Do something. 

103 

104 Do it n times, where n must be a positive integer. The final 

105 result bla-bla is returned. 

106 """ 

107 

108 for i in range(n): 

109 self.a += i 

110 if self.verbose: 

111 print(self.a) 

112 

113 return pi * self.a / n + 1 

114 

115 def reset(self): 

116 """Simple method - no explanation needed.""" 

117 self.a[:] = 0 

118 

119 

120def function(a, b): 

121 """Headline. 

122 

123 Long story ...""" 

124 

125 result = a + b 

126 if debug and mpi.world.rank == 0: 

127 print(result * Ha) 

128 return result