Coverage for python / aubellhop / demo.py: 98%

1"""Demo function for aubellhop. 

2 

3Provides a simple getting started demo that shows how to use bellhop 

4for acoustic propagation calculations. 

5""" 

6 

7from __future__ import annotations 

8 

9import pandas as pd 

10 

11from .environment import Environment 

12from .compute import compute_arrivals 

13 

14 

15def demo() -> pd.DataFrame: 

16 """Run a simple bellhop demonstration and write demo file. 

17 

18 This function: 

19 1. Creates a simple underwater acoustic environment with default settings 

20 2. Computes acoustic ray arrivals using bellhop 

21 3. Prints a summary of the arrival results to the console 

22 4. Writes a standalone bellhop_demo.py file to the current directory 

23 

24 Returns 

25 ------- 

26 results : pandas.DataFrame 

27 DataFrame containing the computed arrival results 

28 

29 Example 

30 ------- 

31 >>> import aubellhop 

32 >>> bellhop.demo() 

33 

34 """ 

35 

36 # Create a simple underwater acoustic environment 

37 print("=" * 60) 

38 print("BELLHOP DEMO - Underwater Acoustic Propagation") 

39 print("=" * 60) 

40 print() 

41 

42 print("Creating acoustic environment with default settings...") 

43 env = Environment( 

44 name='bellhop demo environment', 

45 frequency=25000, # 25 kHz 

46 bottom_depth=25, # 25 m water depth 

47 soundspeed=1500, # 1500 m/s constant sound speed 

48 source_depth=5, # source at 5 m depth 

49 receiver_depth=10, # receiver at 10 m depth 

50 receiver_range=1000, # 1 km range 

51 bottom_soundspeed=1600, # seabed sound speed 

52 bottom_density=1600 # seabed density 

53 ) 

54 

55 print(f" Frequency: {env.frequency} Hz") 

56 print(f" Water depth: {env.bottom_depth} m") 

57 print(f" Sound speed: {env.soundspeed} m/s") 

58 print(f" Source depth: {env.source_depth} m") 

59 print(f" Receiver depth: {env.receiver_depth} m") 

60 print(f" Receiver range: {env.receiver_range} m") 

61 print() 

62 

63 # Compute arrivals 

64 print("Computing acoustic ray arrivals...") 

65 results = compute_arrivals(env) 

66 

67 # Print summary of results 

68 print() 

69 print("=" * 60) 

70 print("ARRIVAL RESULTS") 

71 print("=" * 60) 

72 

73 if "time_of_arrival" in results.columns: 

74 arrivals = results["time_of_arrival"] 

75 num_arrivals = len(arrivals) 

76 

77 print(f"Number of arrivals: {num_arrivals}") 

78 print() 

79 

80 if num_arrivals > 0: 

81 # Convert to list to ensure consistent indexing (pandas Series) 

82 arrival_times = list(arrivals) 

83 print(f"First arrival time: {arrival_times[0]:.6f} seconds") 

84 print(f"Last arrival time: {arrival_times[-1]:.6f} seconds") 

85 print() 

86 

87 # Show first few arrivals 

88 n_show = min(5, num_arrivals) 

89 print(f"First {n_show} arrival times (seconds):") 

90 for i in range(n_show): 

91 print(f" Arrival {i+1}: {arrival_times[i]:.6f} s") 

92 

93 if num_arrivals > n_show: 

94 print(f" ... ({num_arrivals - n_show} more arrivals)") 

95 else: 

96 print("No arrivals computed.") 

97 

98 print() 

99 print("=" * 60) 

100 

101 # Write demo file 

102 demo_filename = "bellhop_demo.py" 

103 print(f"Writing demo script to: {demo_filename}") 

104 

105 demo_code = '''#!/usr/bin/env python3 

106"""BELLHOP Demo Script 

107 

108This script demonstrates basic usage of the bellhop underwater acoustic 

109propagation model. It creates a simple acoustic environment and computes 

110acoustic ray arrivals between a source and receiver. 

111 

112Generated by: bellhop.demo() 

113""" 

114 

115import aubellhop as bh 

116 

117# Create acoustic environment 

118env = bh.Environment( 

119 name='bellhop demo environment', 

120 frequency=25000, # 25 kHz 

121 bottom_depth=25, # 25 m water depth 

122 soundspeed=1500, # 1500 m/s constant sound speed 

123 source_depth=5, # source at 5 m depth 

124 receiver_depth=10, # receiver at 10 m depth 

125 receiver_range=1000, # 1 km range 

126 bottom_soundspeed=1600, # seabed sound speed 

127 bottom_density=1600 # seabed density 

128) 

129 

130print("Environment configuration:") 

131print(f" Frequency: {env.frequency} Hz") 

132print(f" Water depth: {env.bottom_depth} m") 

133print(f" Sound speed: {env.soundspeed} m/s") 

134print(f" Source depth: {env.source_depth} m") 

135print(f" Receiver depth: {env.receiver_depth} m") 

136print(f" Receiver range: {env.receiver_range} m") 

137print() 

138 

139# Compute acoustic arrivals 

140print("Computing acoustic ray arrivals...") 

141results = bh.compute_arrivals(env) 

142 

143# Display results 

144if "time_of_arrival" in results.columns: 

145 arrivals = results["time_of_arrival"] 

146 print(f"\\nNumber of arrivals: {len(arrivals)}") 

147 

148 if len(arrivals) > 0: 

149 # Convert to list to ensure consistent indexing 

150 arrival_times = list(arrivals) 

151 print(f"First arrival time: {arrival_times[0]:.6f} seconds") 

152 print(f"Last arrival time: {arrival_times[-1]:.6f} seconds") 

153 

154 # Show first few arrivals 

155 n_show = min(5, len(arrivals)) 

156 print(f"\\nFirst {n_show} arrival times (seconds):") 

157 for i in range(n_show): 

158 print(f" Arrival {i+1}: {arrival_times[i]:.6f} s") 

159 

160 if len(arrivals) > n_show: 

161 print(f" ... ({len(arrivals) - n_show} more arrivals)") 

162else: 

163 print("No arrivals computed.") 

164 

165print("\\nDemo complete!") 

166''' 

167 

168 with open(demo_filename, 'w') as f: 

169 f.write(demo_code) 

170 

171 print("Demo script written successfully!") 

172 print() 

173 print("To run the demo script again:") 

174 print(f" python3 {demo_filename}") 

175 print() 

176 print("=" * 60) 

177 

178 return results